diff --git a/projects/hwloc/doc/index.php b/projects/hwloc/doc/index.php index bb9e1991d..e93b266ba 100644 --- a/projects/hwloc/doc/index.php +++ b/projects/hwloc/doc/index.php @@ -89,7 +89,7 @@ function print_docs($desc, $letterpdf, $a4pdf, $html) { print($blank_line); -$versions = array("v2.9.3", "v2.9.2", "v2.9.1", "v2.9.0"); +$versions = array("v2.9.3"); $first = 1; foreach ($versions as $key => $v) { print_docs("Release $v (stable" . (!$first ? ", old" : "") . ")", diff --git a/projects/hwloc/doc/v2.9.0/a00089_source.php b/projects/hwloc/doc/v2.9.0/a00089_source.php deleted file mode 100644 index 1c556db5e..000000000 --- a/projects/hwloc/doc/v2.9.0/a00089_source.php +++ /dev/null @@ -1,927 +0,0 @@ - - - - - - - - -
-
-
hwloc.h
-
-
-
1 /*
-
2  * Copyright © 2009 CNRS
-
3  * Copyright © 2009-2022 Inria. All rights reserved.
-
4  * Copyright © 2009-2012 Université Bordeaux
-
5  * Copyright © 2009-2020 Cisco Systems, Inc. All rights reserved.
-
6  * See COPYING in top-level directory.
-
7  */
-
8 
-
9 /*=====================================================================
-
10  * PLEASE GO READ THE DOCUMENTATION!
-
11  * ------------------------------------------------
-
12  * $tarball_directory/doc/doxygen-doc/
-
13  * or
-
14  * https://www.open-mpi.org/projects/hwloc/doc/
-
15  *=====================================================================
-
16  *
-
17  * FAIR WARNING: Do NOT expect to be able to figure out all the
-
18  * subtleties of hwloc by simply reading function prototypes and
-
19  * constant descrptions here in this file.
-
20  *
-
21  * Hwloc has wonderful documentation in both PDF and HTML formats for
-
22  * your reading pleasure. The formal documentation explains a LOT of
-
23  * hwloc-specific concepts, provides definitions, and discusses the
-
24  * "big picture" for many of the things that you'll find here in this
-
25  * header file.
-
26  *
-
27  * The PDF/HTML documentation was generated via Doxygen; much of what
-
28  * you'll see in there is also here in this file. BUT THERE IS A LOT
-
29  * THAT IS IN THE PDF/HTML THAT IS ***NOT*** IN hwloc.h!
-
30  *
-
31  * There are entire paragraph-length descriptions, discussions, and
-
32  * pretty pictures to explain subtle corner cases, provide concrete
-
33  * examples, etc.
-
34  *
-
35  * Please, go read the documentation. :-)
-
36  *
-
37  * Moreover there are several examples of hwloc use under doc/examples
-
38  * in the source tree.
-
39  *
-
40  *=====================================================================*/
-
41 
-
53 #ifndef HWLOC_H
-
54 #define HWLOC_H
-
55 
-
56 #include "hwloc/autogen/config.h"
-
57 
-
58 #include <sys/types.h>
-
59 #include <stdio.h>
-
60 #include <string.h>
-
61 #include <limits.h>
-
62 
-
63 /*
-
64  * Symbol transforms
-
65  */
-
66 #include "hwloc/rename.h"
-
67 
-
68 /*
-
69  * Bitmap definitions
-
70  */
-
71 
-
72 #include "hwloc/bitmap.h"
-
73 
-
74 
-
75 #ifdef __cplusplus
-
76 extern "C" {
-
77 #endif
-
78 
-
79 
-
96 #define HWLOC_API_VERSION 0x00020800
-
97 
-
102 HWLOC_DECLSPEC unsigned hwloc_get_api_version(void);
-
103 
-
105 #define HWLOC_COMPONENT_ABI 7
-
106 
-
140 typedef hwloc_bitmap_t hwloc_cpuset_t;
-
142 typedef hwloc_const_bitmap_t hwloc_const_cpuset_t;
-
143 
-
157 typedef hwloc_bitmap_t hwloc_nodeset_t;
-
160 typedef hwloc_const_bitmap_t hwloc_const_nodeset_t;
-
161 
-
176 typedef enum {
-
177 
-
179 #define HWLOC_OBJ_TYPE_MIN HWLOC_OBJ_MACHINE /* Sentinel value */
-
182  HWLOC_OBJ_MACHINE,
-
191  HWLOC_OBJ_PACKAGE,
-
197  HWLOC_OBJ_CORE,
-
201  HWLOC_OBJ_PU,
-
213  HWLOC_OBJ_L1CACHE,
-
214  HWLOC_OBJ_L2CACHE,
-
215  HWLOC_OBJ_L3CACHE,
-
216  HWLOC_OBJ_L4CACHE,
-
217  HWLOC_OBJ_L5CACHE,
-
219  HWLOC_OBJ_L1ICACHE,
-
220  HWLOC_OBJ_L2ICACHE,
-
221  HWLOC_OBJ_L3ICACHE,
-
223  HWLOC_OBJ_GROUP,
-
236  HWLOC_OBJ_NUMANODE,
-
257  HWLOC_OBJ_BRIDGE,
-
269  HWLOC_OBJ_PCI_DEVICE,
-
279  HWLOC_OBJ_OS_DEVICE,
-
290  HWLOC_OBJ_MISC,
-
305  HWLOC_OBJ_MEMCACHE,
-
318  HWLOC_OBJ_DIE,
-
322  HWLOC_OBJ_TYPE_MAX
-
323 } hwloc_obj_type_t;
-
324 
-
326 typedef enum hwloc_obj_cache_type_e {
-
327  HWLOC_OBJ_CACHE_UNIFIED,
-
328  HWLOC_OBJ_CACHE_DATA,
-
329  HWLOC_OBJ_CACHE_INSTRUCTION
-
330 } hwloc_obj_cache_type_t;
-
331 
-
333 typedef enum hwloc_obj_bridge_type_e {
-
334  HWLOC_OBJ_BRIDGE_HOST,
-
335  HWLOC_OBJ_BRIDGE_PCI
-
336 } hwloc_obj_bridge_type_t;
-
337 
-
339 typedef enum hwloc_obj_osdev_type_e {
-
340  HWLOC_OBJ_OSDEV_BLOCK,
-
342  HWLOC_OBJ_OSDEV_GPU,
-
345  HWLOC_OBJ_OSDEV_NETWORK,
-
347  HWLOC_OBJ_OSDEV_OPENFABRICS,
-
351  HWLOC_OBJ_OSDEV_DMA,
-
353  HWLOC_OBJ_OSDEV_COPROC
-
356 } hwloc_obj_osdev_type_t;
-
357 
-
377 HWLOC_DECLSPEC int hwloc_compare_types (hwloc_obj_type_t type1, hwloc_obj_type_t type2) __hwloc_attribute_const;
-
378 
-
380 #define HWLOC_TYPE_UNORDERED INT_MAX
-
381 
-
390 union hwloc_obj_attr_u;
-
391 
-
396 struct hwloc_obj {
-
397  /* physical information */
-
398  hwloc_obj_type_t type;
-
399  char *subtype;
-
401  unsigned os_index;
-
406 #define HWLOC_UNKNOWN_INDEX (unsigned)-1
-
407 
-
408  char *name;
-
413  hwloc_uint64_t total_memory;
-
415  union hwloc_obj_attr_u *attr;
-
418  /* global position */
-
419  int depth;
-
434  unsigned logical_index;
-
441  /* cousins are all objects of the same type (and depth) across the entire topology */
-
442  struct hwloc_obj *next_cousin;
-
443  struct hwloc_obj *prev_cousin;
-
445  /* children of the same parent are siblings, even if they may have different type and depth */
-
446  struct hwloc_obj *parent;
-
447  unsigned sibling_rank;
-
448  struct hwloc_obj *next_sibling;
-
449  struct hwloc_obj *prev_sibling;
-
452  unsigned arity;
-
456  struct hwloc_obj **children;
-
457  struct hwloc_obj *first_child;
-
458  struct hwloc_obj *last_child;
-
461  int symmetric_subtree;
-
472  unsigned memory_arity;
-
475  struct hwloc_obj *memory_first_child;
-
490  unsigned io_arity;
-
493  struct hwloc_obj *io_first_child;
-
502  unsigned misc_arity;
-
505  struct hwloc_obj *misc_first_child;
-
511  /* cpusets and nodesets */
-
512  hwloc_cpuset_t cpuset;
-
527  hwloc_cpuset_t complete_cpuset;
-
540  hwloc_nodeset_t nodeset;
-
562  hwloc_nodeset_t complete_nodeset;
-
578  struct hwloc_info_s *infos;
-
579  unsigned infos_count;
-
581  /* misc */
-
582  void *userdata;
-
587  hwloc_uint64_t gp_index;
-
592 };
-
596 typedef struct hwloc_obj * hwloc_obj_t;
-
597 
-
599 union hwloc_obj_attr_u {
-
601  struct hwloc_numanode_attr_s {
-
602  hwloc_uint64_t local_memory;
-
603  unsigned page_types_len;
-
609  struct hwloc_memory_page_type_s {
-
610  hwloc_uint64_t size;
-
611  hwloc_uint64_t count;
-
612  } * page_types;
-
613  } numanode;
-
614 
-
616  struct hwloc_cache_attr_s {
-
617  hwloc_uint64_t size;
-
618  unsigned depth;
-
619  unsigned linesize;
-
620  int associativity;
-
622  hwloc_obj_cache_type_t type;
-
623  } cache;
-
625  struct hwloc_group_attr_s {
-
626  unsigned depth;
-
628  unsigned kind;
-
629  unsigned subkind;
-
630  unsigned char dont_merge;
-
631  } group;
-
633  struct hwloc_pcidev_attr_s {
-
634 #ifndef HWLOC_HAVE_32BITS_PCI_DOMAIN
-
635  unsigned short domain; /* Only 16bits PCI domains are supported by default */
-
636 #else
-
637  unsigned int domain; /* 32bits PCI domain support break the library ABI, hence it's disabled by default */
-
638 #endif
-
639  unsigned char bus, dev, func;
-
640  unsigned short class_id;
-
641  unsigned short vendor_id, device_id, subvendor_id, subdevice_id;
-
642  unsigned char revision;
-
643  float linkspeed; /* in GB/s */
-
644  } pcidev;
-
646  struct hwloc_bridge_attr_s {
-
647  union {
-
648  struct hwloc_pcidev_attr_s pci;
-
649  } upstream;
-
650  hwloc_obj_bridge_type_t upstream_type;
-
651  union {
-
652  struct {
-
653 #ifndef HWLOC_HAVE_32BITS_PCI_DOMAIN
-
654  unsigned short domain; /* Only 16bits PCI domains are supported by default */
-
655 #else
-
656  unsigned int domain; /* 32bits PCI domain support break the library ABI, hence it's disabled by default */
-
657 #endif
-
658  unsigned char secondary_bus, subordinate_bus;
-
659  } pci;
-
660  } downstream;
-
661  hwloc_obj_bridge_type_t downstream_type;
-
662  unsigned depth;
-
663  } bridge;
-
665  struct hwloc_osdev_attr_s {
-
666  hwloc_obj_osdev_type_t type;
-
667  } osdev;
-
668 };
-
669 
-
674 struct hwloc_info_s {
-
675  char *name;
-
676  char *value;
-
677 };
-
678 
-
687 struct hwloc_topology;
-
692 typedef struct hwloc_topology * hwloc_topology_t;
-
693 
-
700 HWLOC_DECLSPEC int hwloc_topology_init (hwloc_topology_t *topologyp);
-
701 
-
722 HWLOC_DECLSPEC int hwloc_topology_load(hwloc_topology_t topology);
-
723 
-
728 HWLOC_DECLSPEC void hwloc_topology_destroy (hwloc_topology_t topology);
-
729 
-
740 HWLOC_DECLSPEC int hwloc_topology_dup(hwloc_topology_t *newtopology, hwloc_topology_t oldtopology);
-
741 
-
759 HWLOC_DECLSPEC int hwloc_topology_abi_check(hwloc_topology_t topology);
-
760 
-
772 HWLOC_DECLSPEC void hwloc_topology_check(hwloc_topology_t topology);
-
773 
-
794 HWLOC_DECLSPEC int hwloc_topology_get_depth(hwloc_topology_t __hwloc_restrict topology) __hwloc_attribute_pure;
-
795 
-
819 HWLOC_DECLSPEC int hwloc_get_type_depth (hwloc_topology_t topology, hwloc_obj_type_t type);
-
820 
-
821 enum hwloc_get_type_depth_e {
-
822  HWLOC_TYPE_DEPTH_UNKNOWN = -1,
-
823  HWLOC_TYPE_DEPTH_MULTIPLE = -2,
-
824  HWLOC_TYPE_DEPTH_NUMANODE = -3,
-
825  HWLOC_TYPE_DEPTH_BRIDGE = -4,
-
826  HWLOC_TYPE_DEPTH_PCI_DEVICE = -5,
-
827  HWLOC_TYPE_DEPTH_OS_DEVICE = -6,
-
828  HWLOC_TYPE_DEPTH_MISC = -7,
-
829  HWLOC_TYPE_DEPTH_MEMCACHE = -8
-
830 };
-
831 
-
851 HWLOC_DECLSPEC int hwloc_get_memory_parents_depth (hwloc_topology_t topology);
-
852 
-
866 static __hwloc_inline int
-
867 hwloc_get_type_or_below_depth (hwloc_topology_t topology, hwloc_obj_type_t type) __hwloc_attribute_pure;
-
868 
-
882 static __hwloc_inline int
-
883 hwloc_get_type_or_above_depth (hwloc_topology_t topology, hwloc_obj_type_t type) __hwloc_attribute_pure;
-
884 
-
892 HWLOC_DECLSPEC hwloc_obj_type_t hwloc_get_depth_type (hwloc_topology_t topology, int depth) __hwloc_attribute_pure;
-
893 
-
896 HWLOC_DECLSPEC unsigned hwloc_get_nbobjs_by_depth (hwloc_topology_t topology, int depth) __hwloc_attribute_pure;
-
897 
-
903 static __hwloc_inline int
-
904 hwloc_get_nbobjs_by_type (hwloc_topology_t topology, hwloc_obj_type_t type) __hwloc_attribute_pure;
-
905 
-
910 static __hwloc_inline hwloc_obj_t
-
911 hwloc_get_root_obj (hwloc_topology_t topology) __hwloc_attribute_pure;
-
912 
-
914 HWLOC_DECLSPEC hwloc_obj_t hwloc_get_obj_by_depth (hwloc_topology_t topology, int depth, unsigned idx) __hwloc_attribute_pure;
-
915 
-
922 static __hwloc_inline hwloc_obj_t
-
923 hwloc_get_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx) __hwloc_attribute_pure;
-
924 
-
929 static __hwloc_inline hwloc_obj_t
-
930 hwloc_get_next_obj_by_depth (hwloc_topology_t topology, int depth, hwloc_obj_t prev);
-
931 
-
938 static __hwloc_inline hwloc_obj_t
-
939 hwloc_get_next_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type,
-
940  hwloc_obj_t prev);
-
941 
-
958 HWLOC_DECLSPEC const char * hwloc_obj_type_string (hwloc_obj_type_t type) __hwloc_attribute_const;
-
959 
-
977 HWLOC_DECLSPEC int hwloc_obj_type_snprintf(char * __hwloc_restrict string, size_t size,
-
978  hwloc_obj_t obj,
-
979  int verbose);
-
980 
-
992 HWLOC_DECLSPEC int hwloc_obj_attr_snprintf(char * __hwloc_restrict string, size_t size,
-
993  hwloc_obj_t obj, const char * __hwloc_restrict separator,
-
994  int verbose);
-
995 
-
1019 HWLOC_DECLSPEC int hwloc_type_sscanf(const char *string,
-
1020  hwloc_obj_type_t *typep,
-
1021  union hwloc_obj_attr_u *attrp, size_t attrsize);
-
1022 
-
1044 HWLOC_DECLSPEC int hwloc_type_sscanf_as_depth(const char *string,
-
1045  hwloc_obj_type_t *typep,
-
1046  hwloc_topology_t topology, int *depthp);
-
1047 
-
1063 static __hwloc_inline const char *
-
1064 hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name) __hwloc_attribute_pure;
-
1065 
-
1082 HWLOC_DECLSPEC int hwloc_obj_add_info(hwloc_obj_t obj, const char *name, const char *value);
-
1083 
-
1155 typedef enum {
-
1158  HWLOC_CPUBIND_PROCESS = (1<<0),
-
1159 
-
1162  HWLOC_CPUBIND_THREAD = (1<<1),
-
1163 
-
1187  HWLOC_CPUBIND_STRICT = (1<<2),
-
1188 
-
1204  HWLOC_CPUBIND_NOMEMBIND = (1<<3)
-
1205 } hwloc_cpubind_flags_t;
-
1206 
-
1212 HWLOC_DECLSPEC int hwloc_set_cpubind(hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags);
-
1213 
-
1220 HWLOC_DECLSPEC int hwloc_get_cpubind(hwloc_topology_t topology, hwloc_cpuset_t set, int flags);
-
1221 
-
1233 HWLOC_DECLSPEC int hwloc_set_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_cpuset_t set, int flags);
-
1234 
-
1250 HWLOC_DECLSPEC int hwloc_get_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags);
-
1251 
-
1252 #ifdef hwloc_thread_t
-
1260 HWLOC_DECLSPEC int hwloc_set_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_const_cpuset_t set, int flags);
-
1261 #endif
-
1262 
-
1263 #ifdef hwloc_thread_t
-
1275 HWLOC_DECLSPEC int hwloc_get_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_cpuset_t set, int flags);
-
1276 #endif
-
1277 
-
1295 HWLOC_DECLSPEC int hwloc_get_last_cpu_location(hwloc_topology_t topology, hwloc_cpuset_t set, int flags);
-
1296 
-
1317 HWLOC_DECLSPEC int hwloc_get_proc_last_cpu_location(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags);
-
1318 
-
1398 typedef enum {
-
1406  HWLOC_MEMBIND_DEFAULT = 0,
-
1407 
-
1417  HWLOC_MEMBIND_FIRSTTOUCH = 1,
-
1418 
-
1421  HWLOC_MEMBIND_BIND = 2,
-
1422 
-
1430  HWLOC_MEMBIND_INTERLEAVE = 3,
-
1431 
-
1437  HWLOC_MEMBIND_NEXTTOUCH = 4,
-
1438 
-
1445  HWLOC_MEMBIND_MIXED = -1
-
1446 } hwloc_membind_policy_t;
-
1447 
-
1461 typedef enum {
-
1466  HWLOC_MEMBIND_PROCESS = (1<<0),
-
1467 
-
1471  HWLOC_MEMBIND_THREAD = (1<<1),
-
1472 
-
1479  HWLOC_MEMBIND_STRICT = (1<<2),
-
1480 
-
1485  HWLOC_MEMBIND_MIGRATE = (1<<3),
-
1486 
-
1498  HWLOC_MEMBIND_NOCPUBIND = (1<<4),
-
1499 
-
1509  HWLOC_MEMBIND_BYNODESET = (1<<5)
-
1510 } hwloc_membind_flags_t;
-
1511 
-
1527 HWLOC_DECLSPEC int hwloc_set_membind(hwloc_topology_t topology, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags);
-
1528 
-
1576 HWLOC_DECLSPEC int hwloc_get_membind(hwloc_topology_t topology, hwloc_bitmap_t set, hwloc_membind_policy_t * policy, int flags);
-
1577 
-
1590 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);
-
1591 
-
1634 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);
-
1635 
-
1646 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);
-
1647 
-
1678 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);
-
1679 
-
1700 HWLOC_DECLSPEC int hwloc_get_area_memlocation(hwloc_topology_t topology, const void *addr, size_t len, hwloc_bitmap_t set, int flags);
-
1701 
-
1709 HWLOC_DECLSPEC void *hwloc_alloc(hwloc_topology_t topology, size_t len);
-
1710 
-
1725 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;
-
1726 
-
1739 static __hwloc_inline void *
-
1740 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;
-
1741 
-
1745 HWLOC_DECLSPEC int hwloc_free(hwloc_topology_t topology, void *addr, size_t len);
-
1746 
-
1783 HWLOC_DECLSPEC int hwloc_topology_set_pid(hwloc_topology_t __hwloc_restrict topology, hwloc_pid_t pid);
-
1784 
-
1813 HWLOC_DECLSPEC int hwloc_topology_set_synthetic(hwloc_topology_t __hwloc_restrict topology, const char * __hwloc_restrict description);
-
1814 
-
1841 HWLOC_DECLSPEC int hwloc_topology_set_xml(hwloc_topology_t __hwloc_restrict topology, const char * __hwloc_restrict xmlpath);
-
1842 
-
1869 HWLOC_DECLSPEC int hwloc_topology_set_xmlbuffer(hwloc_topology_t __hwloc_restrict topology, const char * __hwloc_restrict buffer, int size);
-
1870 
-
1873 enum hwloc_topology_components_flag_e {
-
1877  HWLOC_TOPOLOGY_COMPONENTS_FLAG_BLACKLIST = (1UL<<0)
-
1878 };
-
1879 
-
1894 HWLOC_DECLSPEC int hwloc_topology_set_components(hwloc_topology_t __hwloc_restrict topology, unsigned long flags, const char * __hwloc_restrict name);
-
1895 
-
1914 enum hwloc_topology_flags_e {
-
1936  HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED = (1UL<<0),
-
1937 
-
1956  HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM = (1UL<<1),
-
1957 
-
1977  HWLOC_TOPOLOGY_FLAG_THISSYSTEM_ALLOWED_RESOURCES = (1UL<<2),
-
1978 
-
2001  HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT = (1UL<<3),
-
2002 
-
2026  HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_CPUBINDING = (1UL<<4),
-
2027 
-
2048  HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_MEMBINDING = (1UL<<5),
-
2049 
-
2063  HWLOC_TOPOLOGY_FLAG_DONT_CHANGE_BINDING = (1UL<<6),
-
2064 
-
2070  HWLOC_TOPOLOGY_FLAG_NO_DISTANCES = (1UL<<7),
-
2071 
-
2076  HWLOC_TOPOLOGY_FLAG_NO_MEMATTRS = (1UL<<8),
-
2077 
-
2082  HWLOC_TOPOLOGY_FLAG_NO_CPUKINDS = (1UL<<9)
-
2083 };
-
2084 
-
2096 HWLOC_DECLSPEC int hwloc_topology_set_flags (hwloc_topology_t topology, unsigned long flags);
-
2097 
-
2107 HWLOC_DECLSPEC unsigned long hwloc_topology_get_flags (hwloc_topology_t topology);
-
2108 
-
2116 HWLOC_DECLSPEC int hwloc_topology_is_thissystem(hwloc_topology_t __hwloc_restrict topology) __hwloc_attribute_pure;
-
2117 
-
2119 struct hwloc_topology_discovery_support {
-
2121  unsigned char pu;
-
2123  unsigned char numa;
-
2125  unsigned char numa_memory;
-
2127  unsigned char disallowed_pu;
-
2129  unsigned char disallowed_numa;
-
2131  unsigned char cpukind_efficiency;
-
2132 };
-
2133 
-
2139 struct hwloc_topology_cpubind_support {
-
2141  unsigned char set_thisproc_cpubind;
-
2143  unsigned char get_thisproc_cpubind;
-
2145  unsigned char set_proc_cpubind;
-
2147  unsigned char get_proc_cpubind;
-
2149  unsigned char set_thisthread_cpubind;
-
2151  unsigned char get_thisthread_cpubind;
-
2153  unsigned char set_thread_cpubind;
-
2155  unsigned char get_thread_cpubind;
-
2157  unsigned char get_thisproc_last_cpu_location;
-
2159  unsigned char get_proc_last_cpu_location;
-
2161  unsigned char get_thisthread_last_cpu_location;
-
2162 };
-
2163 
-
2169 struct hwloc_topology_membind_support {
-
2171  unsigned char set_thisproc_membind;
-
2173  unsigned char get_thisproc_membind;
-
2175  unsigned char set_proc_membind;
-
2177  unsigned char get_proc_membind;
-
2179  unsigned char set_thisthread_membind;
-
2181  unsigned char get_thisthread_membind;
-
2183  unsigned char set_area_membind;
-
2185  unsigned char get_area_membind;
-
2187  unsigned char alloc_membind;
-
2189  unsigned char firsttouch_membind;
-
2191  unsigned char bind_membind;
-
2193  unsigned char interleave_membind;
-
2195  unsigned char nexttouch_membind;
-
2197  unsigned char migrate_membind;
-
2199  unsigned char get_area_memlocation;
-
2200 };
-
2201 
-
2204 struct hwloc_topology_misc_support {
-
2206  unsigned char imported_support;
-
2207 };
-
2208 
-
2215 struct hwloc_topology_support {
-
2216  struct hwloc_topology_discovery_support *discovery;
-
2217  struct hwloc_topology_cpubind_support *cpubind;
-
2218  struct hwloc_topology_membind_support *membind;
-
2219  struct hwloc_topology_misc_support *misc;
-
2220 };
-
2221 
-
2243 HWLOC_DECLSPEC const struct hwloc_topology_support *hwloc_topology_get_support(hwloc_topology_t __hwloc_restrict topology);
-
2244 
-
2254 enum hwloc_type_filter_e {
-
2260  HWLOC_TYPE_FILTER_KEEP_ALL = 0,
-
2261 
-
2268  HWLOC_TYPE_FILTER_KEEP_NONE = 1,
-
2269 
-
2282  HWLOC_TYPE_FILTER_KEEP_STRUCTURE = 2,
-
2283 
-
2297  HWLOC_TYPE_FILTER_KEEP_IMPORTANT = 3
-
2298 };
-
2299 
-
2302 HWLOC_DECLSPEC int hwloc_topology_set_type_filter(hwloc_topology_t topology, hwloc_obj_type_t type, enum hwloc_type_filter_e filter);
-
2303 
-
2306 HWLOC_DECLSPEC int hwloc_topology_get_type_filter(hwloc_topology_t topology, hwloc_obj_type_t type, enum hwloc_type_filter_e *filter);
-
2307 
-
2312 HWLOC_DECLSPEC int hwloc_topology_set_all_types_filter(hwloc_topology_t topology, enum hwloc_type_filter_e filter);
-
2313 
-
2318 HWLOC_DECLSPEC int hwloc_topology_set_cache_types_filter(hwloc_topology_t topology, enum hwloc_type_filter_e filter);
-
2319 
-
2324 HWLOC_DECLSPEC int hwloc_topology_set_icache_types_filter(hwloc_topology_t topology, enum hwloc_type_filter_e filter);
-
2325 
-
2328 HWLOC_DECLSPEC int hwloc_topology_set_io_types_filter(hwloc_topology_t topology, enum hwloc_type_filter_e filter);
-
2329 
-
2340 HWLOC_DECLSPEC void hwloc_topology_set_userdata(hwloc_topology_t topology, const void *userdata);
-
2341 
-
2347 HWLOC_DECLSPEC void * hwloc_topology_get_userdata(hwloc_topology_t topology);
-
2348 
-
2358 enum hwloc_restrict_flags_e {
-
2364  HWLOC_RESTRICT_FLAG_REMOVE_CPULESS = (1UL<<0),
-
2365 
-
2370  HWLOC_RESTRICT_FLAG_BYNODESET = (1UL<<3),
-
2371 
-
2377  HWLOC_RESTRICT_FLAG_REMOVE_MEMLESS = (1UL<<4),
-
2378 
-
2383  HWLOC_RESTRICT_FLAG_ADAPT_MISC = (1UL<<1),
-
2384 
-
2389  HWLOC_RESTRICT_FLAG_ADAPT_IO = (1UL<<2)
-
2390 };
-
2391 
-
2416 HWLOC_DECLSPEC int hwloc_topology_restrict(hwloc_topology_t __hwloc_restrict topology, hwloc_const_bitmap_t set, unsigned long flags);
-
2417 
-
2419 enum hwloc_allow_flags_e {
-
2424  HWLOC_ALLOW_FLAG_ALL = (1UL<<0),
-
2425 
-
2433  HWLOC_ALLOW_FLAG_LOCAL_RESTRICTIONS = (1UL<<1),
-
2434 
-
2437  HWLOC_ALLOW_FLAG_CUSTOM = (1UL<<2)
-
2438 };
-
2439 
-
2455 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);
-
2456 
-
2478 HWLOC_DECLSPEC hwloc_obj_t hwloc_topology_insert_misc_object(hwloc_topology_t topology, hwloc_obj_t parent, const char *name);
-
2479 
-
2487 HWLOC_DECLSPEC hwloc_obj_t hwloc_topology_alloc_group_object(hwloc_topology_t topology);
-
2488 
-
2535 HWLOC_DECLSPEC hwloc_obj_t hwloc_topology_insert_group_object(hwloc_topology_t topology, hwloc_obj_t group);
-
2536 
-
2546 HWLOC_DECLSPEC int hwloc_obj_add_other_obj_sets(hwloc_obj_t dst, hwloc_obj_t src);
-
2547 
-
2562 HWLOC_DECLSPEC int hwloc_topology_refresh(hwloc_topology_t topology);
-
2563 
-
2568 #ifdef __cplusplus
-
2569 } /* extern "C" */
-
2570 #endif
-
2571 
-
2572 
-
2573 /* high-level helpers */
-
2574 #include "hwloc/helper.h"
-
2575 
-
2576 /* inline code of some functions above */
-
2577 #include "hwloc/inlines.h"
-
2578 
-
2579 /* memory attributes */
-
2580 #include "hwloc/memattrs.h"
-
2581 
-
2582 /* kinds of CPU cores */
-
2583 #include "hwloc/cpukinds.h"
-
2584 
-
2585 /* exporting to XML or synthetic */
-
2586 #include "hwloc/export.h"
-
2587 
-
2588 /* distances */
-
2589 #include "hwloc/distances.h"
-
2590 
-
2591 /* topology diffs */
-
2592 #include "hwloc/diff.h"
-
2593 
-
2594 /* deprecated headers */
-
2595 #include "hwloc/deprecated.h"
-
2596 
-
2597 #endif /* HWLOC_H */
-
hwloc_get_api_version
unsigned hwloc_get_api_version(void)
Indicate at runtime which hwloc API version was used at build time.
-
hwloc_const_cpuset_t
hwloc_const_bitmap_t hwloc_const_cpuset_t
A non-modifiable hwloc_cpuset_t.
Definition: hwloc.h:142
-
hwloc_const_nodeset_t
hwloc_const_bitmap_t hwloc_const_nodeset_t
A non-modifiable hwloc_nodeset_t.
Definition: hwloc.h:160
-
hwloc_nodeset_t
hwloc_bitmap_t hwloc_nodeset_t
A node set is a bitmap whose bits are set according to NUMA memory node physical OS indexes.
Definition: hwloc.h:157
-
hwloc_cpuset_t
hwloc_bitmap_t hwloc_cpuset_t
A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
Definition: hwloc.h:140
-
hwloc_compare_types
int hwloc_compare_types(hwloc_obj_type_t type1, hwloc_obj_type_t type2)
Compare the depth of two object types.
-
hwloc_obj_bridge_type_e
hwloc_obj_bridge_type_e
Type of one side (upstream or downstream) of an I/O bridge.
Definition: hwloc.h:333
-
hwloc_obj_cache_type_t
enum hwloc_obj_cache_type_e hwloc_obj_cache_type_t
Cache type.
-
hwloc_obj_osdev_type_e
hwloc_obj_osdev_type_e
Type of a OS device.
Definition: hwloc.h:339
-
hwloc_obj_cache_type_e
hwloc_obj_cache_type_e
Cache type.
Definition: hwloc.h:326
-
hwloc_obj_osdev_type_t
enum hwloc_obj_osdev_type_e hwloc_obj_osdev_type_t
Type of a OS device.
-
hwloc_obj_bridge_type_t
enum hwloc_obj_bridge_type_e hwloc_obj_bridge_type_t
Type of one side (upstream or downstream) of an I/O bridge.
-
hwloc_obj_type_t
hwloc_obj_type_t
Type of topology object.
Definition: hwloc.h:176
-
HWLOC_OBJ_BRIDGE_HOST
@ HWLOC_OBJ_BRIDGE_HOST
Host-side of a bridge, only possible upstream.
Definition: hwloc.h:334
-
HWLOC_OBJ_BRIDGE_PCI
@ HWLOC_OBJ_BRIDGE_PCI
PCI-side of a bridge.
Definition: hwloc.h:335
-
HWLOC_OBJ_OSDEV_COPROC
@ HWLOC_OBJ_OSDEV_COPROC
Operating system co-processor device. For instance "opencl0d0" for a OpenCL device,...
Definition: hwloc.h:353
-
HWLOC_OBJ_OSDEV_OPENFABRICS
@ HWLOC_OBJ_OSDEV_OPENFABRICS
Operating system openfabrics device. For instance the "mlx4_0" InfiniBand HCA, "hfi1_0" Omni-Path int...
Definition: hwloc.h:347
-
HWLOC_OBJ_OSDEV_BLOCK
@ HWLOC_OBJ_OSDEV_BLOCK
Operating system block device, or non-volatile memory device. For instance "sda" or "dax2....
Definition: hwloc.h:340
-
HWLOC_OBJ_OSDEV_DMA
@ HWLOC_OBJ_OSDEV_DMA
Operating system dma engine device. For instance the "dma0chan0" DMA channel on Linux.
Definition: hwloc.h:351
-
HWLOC_OBJ_OSDEV_GPU
@ HWLOC_OBJ_OSDEV_GPU
Operating system GPU device. For instance ":0.0" for a GL display, "card0" for a Linux DRM device.
Definition: hwloc.h:342
-
HWLOC_OBJ_OSDEV_NETWORK
@ HWLOC_OBJ_OSDEV_NETWORK
Operating system network device. For instance the "eth0" interface on Linux.
Definition: hwloc.h:345
-
HWLOC_OBJ_CACHE_UNIFIED
@ HWLOC_OBJ_CACHE_UNIFIED
Unified cache.
Definition: hwloc.h:327
-
HWLOC_OBJ_CACHE_INSTRUCTION
@ HWLOC_OBJ_CACHE_INSTRUCTION
Instruction cache (filtered out by default).
Definition: hwloc.h:329
-
HWLOC_OBJ_CACHE_DATA
@ HWLOC_OBJ_CACHE_DATA
Data cache.
Definition: hwloc.h:328
-
HWLOC_OBJ_MEMCACHE
@ HWLOC_OBJ_MEMCACHE
Memory-side cache (filtered out by default). A cache in front of a specific NUMA node.
Definition: hwloc.h:305
-
HWLOC_OBJ_L2ICACHE
@ HWLOC_OBJ_L2ICACHE
Level 2 instruction Cache (filtered out by default).
Definition: hwloc.h:220
-
HWLOC_OBJ_L2CACHE
@ HWLOC_OBJ_L2CACHE
Level 2 Data (or Unified) Cache.
Definition: hwloc.h:214
-
HWLOC_OBJ_MISC
@ HWLOC_OBJ_MISC
Miscellaneous objects (filtered out by default). Objects without particular meaning,...
Definition: hwloc.h:290
-
HWLOC_OBJ_L3CACHE
@ HWLOC_OBJ_L3CACHE
Level 3 Data (or Unified) Cache.
Definition: hwloc.h:215
-
HWLOC_OBJ_MACHINE
@ HWLOC_OBJ_MACHINE
Machine. A set of processors and memory with cache coherency.
Definition: hwloc.h:182
-
HWLOC_OBJ_OS_DEVICE
@ HWLOC_OBJ_OS_DEVICE
Operating system device (filtered out by default).
Definition: hwloc.h:279
-
HWLOC_OBJ_GROUP
@ HWLOC_OBJ_GROUP
Group objects. Objects which do not fit in the above but are detected by hwloc and are useful to take...
Definition: hwloc.h:223
-
HWLOC_OBJ_L4CACHE
@ HWLOC_OBJ_L4CACHE
Level 4 Data (or Unified) Cache.
Definition: hwloc.h:216
-
HWLOC_OBJ_L1CACHE
@ HWLOC_OBJ_L1CACHE
Level 1 Data (or Unified) Cache.
Definition: hwloc.h:213
-
HWLOC_OBJ_PCI_DEVICE
@ HWLOC_OBJ_PCI_DEVICE
PCI device (filtered out by default).
Definition: hwloc.h:269
-
HWLOC_OBJ_L5CACHE
@ HWLOC_OBJ_L5CACHE
Level 5 Data (or Unified) Cache.
Definition: hwloc.h:217
-
HWLOC_OBJ_BRIDGE
@ HWLOC_OBJ_BRIDGE
Bridge (filtered out by default). Any bridge (or PCI switch) that connects the host or an I/O bus,...
Definition: hwloc.h:257
-
HWLOC_OBJ_NUMANODE
@ HWLOC_OBJ_NUMANODE
NUMA node. An object that contains memory that is directly and byte-accessible to the host processors...
Definition: hwloc.h:236
-
HWLOC_OBJ_PACKAGE
@ HWLOC_OBJ_PACKAGE
Physical package. The physical package that usually gets inserted into a socket on the motherboard....
Definition: hwloc.h:191
-
HWLOC_OBJ_PU
@ HWLOC_OBJ_PU
Processing Unit, or (Logical) Processor. An execution unit (may share a core with some other logical ...
Definition: hwloc.h:201
-
HWLOC_OBJ_L3ICACHE
@ HWLOC_OBJ_L3ICACHE
Level 3 instruction Cache (filtered out by default).
Definition: hwloc.h:221
-
HWLOC_OBJ_CORE
@ HWLOC_OBJ_CORE
Core. A computation unit (may be shared by several PUs, aka logical processors).
Definition: hwloc.h:197
-
HWLOC_OBJ_DIE
@ HWLOC_OBJ_DIE
Die within a physical package. A subpart of the physical package, that contains multiple cores.
Definition: hwloc.h:318
-
HWLOC_OBJ_L1ICACHE
@ HWLOC_OBJ_L1ICACHE
Level 1 instruction Cache (filtered out by default).
Definition: hwloc.h:219
-
hwloc_obj_t
struct hwloc_obj * hwloc_obj_t
Convenience typedef; a pointer to a struct hwloc_obj.
Definition: hwloc.h:596
-
hwloc_topology_init
int hwloc_topology_init(hwloc_topology_t *topologyp)
Allocate a topology context.
-
hwloc_topology_abi_check
int hwloc_topology_abi_check(hwloc_topology_t topology)
Verify that the topology is compatible with the current hwloc library.
-
hwloc_topology_dup
int hwloc_topology_dup(hwloc_topology_t *newtopology, hwloc_topology_t oldtopology)
Duplicate a topology.
-
hwloc_topology_t
struct hwloc_topology * hwloc_topology_t
Topology context.
Definition: hwloc.h:692
-
hwloc_topology_destroy
void hwloc_topology_destroy(hwloc_topology_t topology)
Terminate and free a topology context.
-
hwloc_topology_load
int hwloc_topology_load(hwloc_topology_t topology)
Build the actual topology.
-
hwloc_topology_check
void hwloc_topology_check(hwloc_topology_t topology)
Run internal checks on a topology structure.
-
hwloc_get_nbobjs_by_depth
unsigned hwloc_get_nbobjs_by_depth(hwloc_topology_t topology, int depth)
Returns the width of level at depth depth.
-
hwloc_get_root_obj
static hwloc_obj_t hwloc_get_root_obj(hwloc_topology_t topology)
Returns the top-object of the topology-tree.
-
hwloc_get_obj_by_depth
hwloc_obj_t hwloc_get_obj_by_depth(hwloc_topology_t topology, int depth, unsigned idx)
Returns the topology object at logical index idx from depth depth.
-
hwloc_get_depth_type
hwloc_obj_type_t hwloc_get_depth_type(hwloc_topology_t topology, int depth)
Returns the type of objects at depth depth.
-
hwloc_get_obj_by_type
static hwloc_obj_t hwloc_get_obj_by_type(hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx)
Returns the topology object at logical index idx with type type.
-
hwloc_get_next_obj_by_type
static hwloc_obj_t hwloc_get_next_obj_by_type(hwloc_topology_t topology, hwloc_obj_type_t type, hwloc_obj_t prev)
Returns the next object of type type.
-
hwloc_get_nbobjs_by_type
static int hwloc_get_nbobjs_by_type(hwloc_topology_t topology, hwloc_obj_type_t type)
Returns the width of level type type.
-
hwloc_get_type_or_below_depth
static int hwloc_get_type_or_below_depth(hwloc_topology_t topology, hwloc_obj_type_t type)
Returns the depth of objects of type type or below.
-
hwloc_get_type_or_above_depth
static int hwloc_get_type_or_above_depth(hwloc_topology_t topology, hwloc_obj_type_t type)
Returns the depth of objects of type type or above.
-
hwloc_get_type_depth
int hwloc_get_type_depth(hwloc_topology_t topology, hwloc_obj_type_t type)
Returns the depth of objects of type type.
-
hwloc_get_next_obj_by_depth
static hwloc_obj_t hwloc_get_next_obj_by_depth(hwloc_topology_t topology, int depth, hwloc_obj_t prev)
Returns the next object at depth depth.
-
hwloc_topology_get_depth
int hwloc_topology_get_depth(hwloc_topology_t restrict topology)
Get the depth of the hierarchical tree of objects.
-
hwloc_get_memory_parents_depth
int hwloc_get_memory_parents_depth(hwloc_topology_t topology)
Return the depth of parents where memory objects are attached.
-
hwloc_get_type_depth_e
hwloc_get_type_depth_e
Definition: hwloc.h:821
-
HWLOC_TYPE_DEPTH_UNKNOWN
@ HWLOC_TYPE_DEPTH_UNKNOWN
No object of given type exists in the topology.
Definition: hwloc.h:822
-
HWLOC_TYPE_DEPTH_NUMANODE
@ HWLOC_TYPE_DEPTH_NUMANODE
Virtual depth for NUMA nodes.
Definition: hwloc.h:824
-
HWLOC_TYPE_DEPTH_MEMCACHE
@ HWLOC_TYPE_DEPTH_MEMCACHE
Virtual depth for MemCache object.
Definition: hwloc.h:829
-
HWLOC_TYPE_DEPTH_MISC
@ HWLOC_TYPE_DEPTH_MISC
Virtual depth for Misc object.
Definition: hwloc.h:828
-
HWLOC_TYPE_DEPTH_PCI_DEVICE
@ HWLOC_TYPE_DEPTH_PCI_DEVICE
Virtual depth for PCI device object level.
Definition: hwloc.h:826
-
HWLOC_TYPE_DEPTH_MULTIPLE
@ HWLOC_TYPE_DEPTH_MULTIPLE
Objects of given type exist at different depth in the topology (only for Groups).
Definition: hwloc.h:823
-
HWLOC_TYPE_DEPTH_BRIDGE
@ HWLOC_TYPE_DEPTH_BRIDGE
Virtual depth for bridge object level.
Definition: hwloc.h:825
-
HWLOC_TYPE_DEPTH_OS_DEVICE
@ HWLOC_TYPE_DEPTH_OS_DEVICE
Virtual depth for software device object level.
Definition: hwloc.h:827
-
hwloc_type_sscanf
int hwloc_type_sscanf(const char *string, hwloc_obj_type_t *typep, union hwloc_obj_attr_u *attrp, size_t attrsize)
Return an object type and attributes from a type string.
-
hwloc_type_sscanf_as_depth
int hwloc_type_sscanf_as_depth(const char *string, hwloc_obj_type_t *typep, hwloc_topology_t topology, int *depthp)
Return an object type and its level depth from a type string.
-
hwloc_obj_type_string
const char * hwloc_obj_type_string(hwloc_obj_type_t type)
Return a constant stringified object type.
-
hwloc_obj_attr_snprintf
int hwloc_obj_attr_snprintf(char *restrict string, size_t size, hwloc_obj_t obj, const char *restrict separator, int verbose)
Stringify the attributes of a given topology object into a human-readable form.
-
hwloc_obj_type_snprintf
int hwloc_obj_type_snprintf(char *restrict string, size_t size, hwloc_obj_t obj, int verbose)
Stringify the type of a given topology object into a human-readable form.
-
hwloc_obj_get_info_by_name
static const char * hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name)
Search the given key name in object infos and return the corresponding value.
-
hwloc_obj_add_info
int hwloc_obj_add_info(hwloc_obj_t obj, const char *name, const char *value)
Add the given info name and value pair to the given object.
-
hwloc_cpubind_flags_t
hwloc_cpubind_flags_t
Process/Thread binding flags.
Definition: hwloc.h:1155
-
hwloc_set_proc_cpubind
int hwloc_set_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_cpuset_t set, int flags)
Bind a process pid on CPUs given in physical bitmap set.
-
hwloc_set_cpubind
int hwloc_set_cpubind(hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags)
Bind current process or thread on CPUs given in physical bitmap set.
-
hwloc_get_proc_last_cpu_location
int hwloc_get_proc_last_cpu_location(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags)
Get the last physical CPU where a process ran.
-
hwloc_get_proc_cpubind
int hwloc_get_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags)
Get the current physical binding of process pid.
-
hwloc_get_cpubind
int hwloc_get_cpubind(hwloc_topology_t topology, hwloc_cpuset_t set, int flags)
Get current process or thread binding.
-
hwloc_set_thread_cpubind
int hwloc_set_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_const_cpuset_t set, int flags)
Bind a thread thread on CPUs given in physical bitmap set.
-
hwloc_get_thread_cpubind
int hwloc_get_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_cpuset_t set, int flags)
Get the current physical binding of thread tid.
-
hwloc_get_last_cpu_location
int hwloc_get_last_cpu_location(hwloc_topology_t topology, hwloc_cpuset_t set, int flags)
Get the last physical CPU where the current process or thread ran.
-
HWLOC_CPUBIND_PROCESS
@ HWLOC_CPUBIND_PROCESS
Bind all threads of the current (possibly) multithreaded process.
Definition: hwloc.h:1158
-
HWLOC_CPUBIND_NOMEMBIND
@ HWLOC_CPUBIND_NOMEMBIND
Avoid any effect on memory binding.
Definition: hwloc.h:1204
-
HWLOC_CPUBIND_STRICT
@ HWLOC_CPUBIND_STRICT
Request for strict binding from the OS.
Definition: hwloc.h:1187
-
HWLOC_CPUBIND_THREAD
@ HWLOC_CPUBIND_THREAD
Bind current thread of current process.
Definition: hwloc.h:1162
-
hwloc_set_membind
int hwloc_set_membind(hwloc_topology_t topology, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags)
Set the default memory binding policy of the current process or thread to prefer the NUMA node(s) spe...
-
hwloc_alloc_membind
void * hwloc_alloc_membind(hwloc_topology_t topology, size_t len, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags)
Allocate some memory on NUMA memory nodes specified by set.
-
hwloc_get_proc_membind
int hwloc_get_proc_membind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_bitmap_t set, hwloc_membind_policy_t *policy, int flags)
Query the default memory binding policy and physical locality of the specified process.
-
hwloc_free
int hwloc_free(hwloc_topology_t topology, void *addr, size_t len)
Free memory that was previously allocated by hwloc_alloc() or hwloc_alloc_membind().
-
hwloc_get_area_memlocation
int hwloc_get_area_memlocation(hwloc_topology_t topology, const void *addr, size_t len, hwloc_bitmap_t set, int flags)
Get the NUMA nodes where memory identified by (addr, len ) is physically allocated.
-
hwloc_alloc
void * hwloc_alloc(hwloc_topology_t topology, size_t len)
Allocate some memory.
-
hwloc_get_area_membind
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)
Query the CPUs near the physical NUMA node(s) and binding policy of the memory identified by (addr,...
-
hwloc_membind_flags_t
hwloc_membind_flags_t
Memory binding flags.
Definition: hwloc.h:1461
-
hwloc_alloc_membind_policy
static void * hwloc_alloc_membind_policy(hwloc_topology_t topology, size_t len, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags)
Allocate some memory on NUMA memory nodes specified by set.
-
hwloc_set_proc_membind
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)
Set the default memory binding policy of the specified process to prefer the NUMA node(s) specified b...
-
hwloc_membind_policy_t
hwloc_membind_policy_t
Memory binding policy.
Definition: hwloc.h:1398
-
hwloc_get_membind
int hwloc_get_membind(hwloc_topology_t topology, hwloc_bitmap_t set, hwloc_membind_policy_t *policy, int flags)
Query the default memory binding policy and physical locality of the current process or thread.
-
hwloc_set_area_membind
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)
Bind the already-allocated memory identified by (addr, len) to the NUMA node(s) specified by set.
-
HWLOC_MEMBIND_STRICT
@ HWLOC_MEMBIND_STRICT
Definition: hwloc.h:1479
-
HWLOC_MEMBIND_PROCESS
@ HWLOC_MEMBIND_PROCESS
Set policy for all threads of the specified (possibly multithreaded) process. This flag is mutually e...
Definition: hwloc.h:1466
-
HWLOC_MEMBIND_THREAD
@ HWLOC_MEMBIND_THREAD
Set policy for a specific thread of the current process. This flag is mutually exclusive with HWLOC_M...
Definition: hwloc.h:1471
-
HWLOC_MEMBIND_BYNODESET
@ HWLOC_MEMBIND_BYNODESET
Consider the bitmap argument as a nodeset.
Definition: hwloc.h:1509
-
HWLOC_MEMBIND_MIGRATE
@ HWLOC_MEMBIND_MIGRATE
Migrate existing allocated memory. If the memory cannot be migrated and the HWLOC_MEMBIND_STRICT flag...
Definition: hwloc.h:1485
-
HWLOC_MEMBIND_NOCPUBIND
@ HWLOC_MEMBIND_NOCPUBIND
Avoid any effect on CPU binding.
Definition: hwloc.h:1498
-
HWLOC_MEMBIND_DEFAULT
@ HWLOC_MEMBIND_DEFAULT
Reset the memory allocation policy to the system default. Depending on the operating system,...
Definition: hwloc.h:1406
-
HWLOC_MEMBIND_MIXED
@ HWLOC_MEMBIND_MIXED
Returned by get_membind() functions when multiple threads or parts of a memory area have differing me...
Definition: hwloc.h:1445
-
HWLOC_MEMBIND_FIRSTTOUCH
@ HWLOC_MEMBIND_FIRSTTOUCH
Allocate each memory page individually on the local NUMA node of the thread that touches it.
Definition: hwloc.h:1417
-
HWLOC_MEMBIND_BIND
@ HWLOC_MEMBIND_BIND
Allocate memory on the specified nodes.
Definition: hwloc.h:1421
-
HWLOC_MEMBIND_INTERLEAVE
@ HWLOC_MEMBIND_INTERLEAVE
Allocate memory on the given nodes in an interleaved / round-robin manner. The precise layout of the ...
Definition: hwloc.h:1430
-
HWLOC_MEMBIND_NEXTTOUCH
@ HWLOC_MEMBIND_NEXTTOUCH
For each page bound with this policy, by next time it is touched (and next time only),...
Definition: hwloc.h:1437
-
hwloc_topology_set_xmlbuffer
int hwloc_topology_set_xmlbuffer(hwloc_topology_t restrict topology, const char *restrict buffer, int size)
Enable XML based topology using a memory buffer (instead of a file, as with hwloc_topology_set_xml())...
-
hwloc_topology_set_pid
int hwloc_topology_set_pid(hwloc_topology_t restrict topology, hwloc_pid_t pid)
Change which process the topology is viewed from.
-
hwloc_topology_set_synthetic
int hwloc_topology_set_synthetic(hwloc_topology_t restrict topology, const char *restrict description)
Enable synthetic topology.
-
hwloc_topology_set_xml
int hwloc_topology_set_xml(hwloc_topology_t restrict topology, const char *restrict xmlpath)
Enable XML-file based topology.
-
hwloc_topology_components_flag_e
hwloc_topology_components_flag_e
Flags to be passed to hwloc_topology_set_components()
Definition: hwloc.h:1873
-
hwloc_topology_set_components
int hwloc_topology_set_components(hwloc_topology_t restrict topology, unsigned long flags, const char *restrict name)
Prevent a discovery component from being used for a topology.
-
HWLOC_TOPOLOGY_COMPONENTS_FLAG_BLACKLIST
@ HWLOC_TOPOLOGY_COMPONENTS_FLAG_BLACKLIST
Blacklist the target component from being used.
Definition: hwloc.h:1877
-
hwloc_topology_get_flags
unsigned long hwloc_topology_get_flags(hwloc_topology_t topology)
Get OR'ed flags of a topology.
-
hwloc_topology_set_io_types_filter
int hwloc_topology_set_io_types_filter(hwloc_topology_t topology, enum hwloc_type_filter_e filter)
Set the filtering for all I/O object types.
-
hwloc_topology_get_type_filter
int hwloc_topology_get_type_filter(hwloc_topology_t topology, hwloc_obj_type_t type, enum hwloc_type_filter_e *filter)
Get the current filtering for the given object type.
-
hwloc_topology_set_userdata
void hwloc_topology_set_userdata(hwloc_topology_t topology, const void *userdata)
Set the topology-specific userdata pointer.
-
hwloc_topology_set_cache_types_filter
int hwloc_topology_set_cache_types_filter(hwloc_topology_t topology, enum hwloc_type_filter_e filter)
Set the filtering for all CPU cache object types.
-
hwloc_topology_set_icache_types_filter
int hwloc_topology_set_icache_types_filter(hwloc_topology_t topology, enum hwloc_type_filter_e filter)
Set the filtering for all CPU instruction cache object types.
-
hwloc_topology_is_thissystem
int hwloc_topology_is_thissystem(hwloc_topology_t restrict topology)
Does the topology context come from this system?
-
hwloc_topology_get_userdata
void * hwloc_topology_get_userdata(hwloc_topology_t topology)
Retrieve the topology-specific userdata pointer.
-
hwloc_type_filter_e
hwloc_type_filter_e
Type filtering flags.
Definition: hwloc.h:2254
-
hwloc_topology_set_all_types_filter
int hwloc_topology_set_all_types_filter(hwloc_topology_t topology, enum hwloc_type_filter_e filter)
Set the filtering for all object types.
-
hwloc_topology_set_flags
int hwloc_topology_set_flags(hwloc_topology_t topology, unsigned long flags)
Set OR'ed flags to non-yet-loaded topology.
-
hwloc_topology_get_support
const struct hwloc_topology_support * hwloc_topology_get_support(hwloc_topology_t restrict topology)
Retrieve the topology support.
-
hwloc_topology_set_type_filter
int hwloc_topology_set_type_filter(hwloc_topology_t topology, hwloc_obj_type_t type, enum hwloc_type_filter_e filter)
Set the filtering for the given object type.
-
hwloc_topology_flags_e
hwloc_topology_flags_e
Flags to be set onto a topology context before load.
Definition: hwloc.h:1914
-
HWLOC_TYPE_FILTER_KEEP_NONE
@ HWLOC_TYPE_FILTER_KEEP_NONE
Ignore all objects of this type.
Definition: hwloc.h:2268
-
HWLOC_TYPE_FILTER_KEEP_IMPORTANT
@ HWLOC_TYPE_FILTER_KEEP_IMPORTANT
Only keep likely-important objects of the given type.
Definition: hwloc.h:2297
-
HWLOC_TYPE_FILTER_KEEP_STRUCTURE
@ HWLOC_TYPE_FILTER_KEEP_STRUCTURE
Only ignore objects if their entire level does not bring any structure.
Definition: hwloc.h:2282
-
HWLOC_TYPE_FILTER_KEEP_ALL
@ HWLOC_TYPE_FILTER_KEEP_ALL
Keep all objects of this type.
Definition: hwloc.h:2260
-
HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED
@ HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED
Detect the whole system, ignore reservations, include disallowed objects.
Definition: hwloc.h:1936
-
HWLOC_TOPOLOGY_FLAG_THISSYSTEM_ALLOWED_RESOURCES
@ HWLOC_TOPOLOGY_FLAG_THISSYSTEM_ALLOWED_RESOURCES
Get the set of allowed resources from the local operating system even if the topology was loaded from...
Definition: hwloc.h:1977
-
HWLOC_TOPOLOGY_FLAG_NO_CPUKINDS
@ HWLOC_TOPOLOGY_FLAG_NO_CPUKINDS
Ignore CPU Kinds.
Definition: hwloc.h:2082
-
HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_MEMBINDING
@ HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_MEMBINDING
Do not consider resources outside of the process memory binding.
Definition: hwloc.h:2048
-
HWLOC_TOPOLOGY_FLAG_NO_DISTANCES
@ HWLOC_TOPOLOGY_FLAG_NO_DISTANCES
Ignore distances.
Definition: hwloc.h:2070
-
HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM
@ HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM
Assume that the selected backend provides the topology for the system on which we are running.
Definition: hwloc.h:1956
-
HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_CPUBINDING
@ HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_CPUBINDING
Do not consider resources outside of the process CPU binding.
Definition: hwloc.h:2026
-
HWLOC_TOPOLOGY_FLAG_NO_MEMATTRS
@ HWLOC_TOPOLOGY_FLAG_NO_MEMATTRS
Ignore memory attributes.
Definition: hwloc.h:2076
-
HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT
@ HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT
Import support from the imported topology.
Definition: hwloc.h:2001
-
HWLOC_TOPOLOGY_FLAG_DONT_CHANGE_BINDING
@ HWLOC_TOPOLOGY_FLAG_DONT_CHANGE_BINDING
Do not ever modify the process or thread binding during discovery.
Definition: hwloc.h:2063
-
hwloc_topology_insert_group_object
hwloc_obj_t hwloc_topology_insert_group_object(hwloc_topology_t topology, hwloc_obj_t group)
Add more structure to the topology by adding an intermediate Group.
-
hwloc_allow_flags_e
hwloc_allow_flags_e
Flags to be given to hwloc_topology_allow().
Definition: hwloc.h:2419
-
hwloc_topology_alloc_group_object
hwloc_obj_t hwloc_topology_alloc_group_object(hwloc_topology_t topology)
Allocate a Group object to insert later with hwloc_topology_insert_group_object().
-
hwloc_topology_refresh
int hwloc_topology_refresh(hwloc_topology_t topology)
Refresh internal structures after topology modification.
-
hwloc_topology_restrict
int hwloc_topology_restrict(hwloc_topology_t restrict topology, hwloc_const_bitmap_t set, unsigned long flags)
Restrict the topology to the given CPU set or nodeset.
-
hwloc_restrict_flags_e
hwloc_restrict_flags_e
Flags to be given to hwloc_topology_restrict().
Definition: hwloc.h:2358
-
hwloc_obj_add_other_obj_sets
int hwloc_obj_add_other_obj_sets(hwloc_obj_t dst, hwloc_obj_t src)
Setup object cpusets/nodesets by OR'ing another object's sets.
-
hwloc_topology_insert_misc_object
hwloc_obj_t hwloc_topology_insert_misc_object(hwloc_topology_t topology, hwloc_obj_t parent, const char *name)
Add a MISC object as a leaf of the topology.
-
hwloc_topology_allow
int hwloc_topology_allow(hwloc_topology_t restrict topology, hwloc_const_cpuset_t cpuset, hwloc_const_nodeset_t nodeset, unsigned long flags)
Change the sets of allowed PUs and NUMA nodes in the topology.
-
HWLOC_ALLOW_FLAG_CUSTOM
@ HWLOC_ALLOW_FLAG_CUSTOM
Allow a custom set of objects, given to hwloc_topology_allow() as cpuset and/or nodeset parameters.
Definition: hwloc.h:2437
-
HWLOC_ALLOW_FLAG_LOCAL_RESTRICTIONS
@ HWLOC_ALLOW_FLAG_LOCAL_RESTRICTIONS
Only allow objects that are available to the current process.
Definition: hwloc.h:2433
-
HWLOC_ALLOW_FLAG_ALL
@ HWLOC_ALLOW_FLAG_ALL
Mark all objects as allowed in the topology.
Definition: hwloc.h:2424
-
HWLOC_RESTRICT_FLAG_ADAPT_MISC
@ HWLOC_RESTRICT_FLAG_ADAPT_MISC
Move Misc objects to ancestors if their parents are removed during restriction. If this flag is not s...
Definition: hwloc.h:2383
-
HWLOC_RESTRICT_FLAG_REMOVE_CPULESS
@ HWLOC_RESTRICT_FLAG_REMOVE_CPULESS
Remove all objects that became CPU-less. By default, only objects that contain no PU and no memory ar...
Definition: hwloc.h:2364
-
HWLOC_RESTRICT_FLAG_ADAPT_IO
@ HWLOC_RESTRICT_FLAG_ADAPT_IO
Move I/O objects to ancestors if their parents are removed during restriction. If this flag is not se...
Definition: hwloc.h:2389
-
HWLOC_RESTRICT_FLAG_BYNODESET
@ HWLOC_RESTRICT_FLAG_BYNODESET
Restrict by nodeset instead of CPU set. Only keep objects whose nodeset is included or partially incl...
Definition: hwloc.h:2370
-
HWLOC_RESTRICT_FLAG_REMOVE_MEMLESS
@ HWLOC_RESTRICT_FLAG_REMOVE_MEMLESS
Remove all objects that became Memory-less. By default, only objects that contain no PU and no memory...
Definition: hwloc.h:2377
-
hwloc_bitmap_t
struct hwloc_bitmap_s * hwloc_bitmap_t
Set of bits represented as an opaque pointer to an internal bitmap.
Definition: bitmap.h:68
-
hwloc_const_bitmap_t
const struct hwloc_bitmap_s * hwloc_const_bitmap_t
a non-modifiable hwloc_bitmap_t
Definition: bitmap.h:70
-
hwloc_obj
Structure of a topology object.
Definition: hwloc.h:396
-
hwloc_obj::children
struct hwloc_obj ** children
Normal children, children[0 .. arity -1].
Definition: hwloc.h:456
-
hwloc_obj::nodeset
hwloc_nodeset_t nodeset
NUMA nodes covered by this object or containing this object.
Definition: hwloc.h:540
-
hwloc_obj::logical_index
unsigned logical_index
Horizontal index in the whole list of similar objects, hence guaranteed unique across the entire mach...
Definition: hwloc.h:434
-
hwloc_obj::symmetric_subtree
int symmetric_subtree
Set if the subtree of normal objects below this object is symmetric, which means all normal children ...
Definition: hwloc.h:461
-
hwloc_obj::misc_arity
unsigned misc_arity
Number of Misc children. These children are listed in misc_first_child.
Definition: hwloc.h:502
-
hwloc_obj::depth
int depth
Vertical index in the hierarchy.
Definition: hwloc.h:419
-
hwloc_obj::misc_first_child
struct hwloc_obj * misc_first_child
First Misc child. Misc objects are listed here (misc_arity and misc_first_child) instead of in the no...
Definition: hwloc.h:505
-
hwloc_obj::subtype
char * subtype
Subtype string to better describe the type field.
Definition: hwloc.h:399
-
hwloc_obj::os_index
unsigned os_index
OS-provided physical index number. It is not guaranteed unique across the entire machine,...
Definition: hwloc.h:401
-
hwloc_obj::cpuset
hwloc_cpuset_t cpuset
CPUs covered by this object.
Definition: hwloc.h:512
-
hwloc_obj::memory_arity
unsigned memory_arity
Number of Memory children. These children are listed in memory_first_child.
Definition: hwloc.h:472
-
hwloc_obj::total_memory
hwloc_uint64_t total_memory
Total memory (in bytes) in NUMA nodes below this object.
Definition: hwloc.h:413
-
hwloc_obj::userdata
void * userdata
Application-given private data pointer, initialized to NULL, use it as you wish. See hwloc_topology_s...
Definition: hwloc.h:582
-
hwloc_obj::io_arity
unsigned io_arity
Number of I/O children. These children are listed in io_first_child.
Definition: hwloc.h:490
-
hwloc_obj::prev_sibling
struct hwloc_obj * prev_sibling
Previous object below the same parent (inside the same list of children).
Definition: hwloc.h:449
-
hwloc_obj::next_sibling
struct hwloc_obj * next_sibling
Next object below the same parent (inside the same list of children).
Definition: hwloc.h:448
-
hwloc_obj::last_child
struct hwloc_obj * last_child
Last normal child.
Definition: hwloc.h:458
-
hwloc_obj::next_cousin
struct hwloc_obj * next_cousin
Next object of same type and depth.
Definition: hwloc.h:442
-
hwloc_obj::infos
struct hwloc_info_s * infos
Array of stringified info type=name.
Definition: hwloc.h:578
-
hwloc_obj::io_first_child
struct hwloc_obj * io_first_child
First I/O child. Bridges, PCI and OS devices are listed here (io_arity and io_first_child) instead of...
Definition: hwloc.h:493
-
hwloc_obj::complete_cpuset
hwloc_cpuset_t complete_cpuset
The complete CPU set of processors of this object,.
Definition: hwloc.h:527
-
hwloc_obj::gp_index
hwloc_uint64_t gp_index
Global persistent index. Generated by hwloc, unique across the topology (contrary to os_index) and pe...
Definition: hwloc.h:587
-
hwloc_obj::infos_count
unsigned infos_count
Size of infos array.
Definition: hwloc.h:579
-
hwloc_obj::sibling_rank
unsigned sibling_rank
Index in parent's children[] array. Or the index in parent's Memory, I/O or Misc children list.
Definition: hwloc.h:447
-
hwloc_obj::arity
unsigned arity
Number of normal children. Memory, Misc and I/O children are not listed here but rather in their dedi...
Definition: hwloc.h:452
-
hwloc_obj::name
char * name
Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name str...
Definition: hwloc.h:408
-
hwloc_obj::memory_first_child
struct hwloc_obj * memory_first_child
First Memory child. NUMA nodes and Memory-side caches are listed here (memory_arity and memory_first_...
Definition: hwloc.h:475
-
hwloc_obj::complete_nodeset
hwloc_nodeset_t complete_nodeset
The complete NUMA node set of this object,.
Definition: hwloc.h:562
-
hwloc_obj::prev_cousin
struct hwloc_obj * prev_cousin
Previous object of same type and depth.
Definition: hwloc.h:443
-
hwloc_obj::type
hwloc_obj_type_t type
Type of object.
Definition: hwloc.h:398
-
hwloc_obj::attr
union hwloc_obj_attr_u * attr
Object type-specific Attributes, may be NULL if no attribute value was found.
Definition: hwloc.h:415
-
hwloc_obj::parent
struct hwloc_obj * parent
Parent, NULL if root (Machine object)
Definition: hwloc.h:446
-
hwloc_obj::first_child
struct hwloc_obj * first_child
First normal child.
Definition: hwloc.h:457
-
hwloc_obj_attr_u
Object type-specific Attributes.
Definition: hwloc.h:599
-
hwloc_obj_attr_u::pcidev
struct hwloc_obj_attr_u::hwloc_pcidev_attr_s pcidev
-
hwloc_obj_attr_u::bridge
struct hwloc_obj_attr_u::hwloc_bridge_attr_s bridge
-
hwloc_obj_attr_u::cache
struct hwloc_obj_attr_u::hwloc_cache_attr_s cache
-
hwloc_obj_attr_u::group
struct hwloc_obj_attr_u::hwloc_group_attr_s group
-
hwloc_obj_attr_u::osdev
struct hwloc_obj_attr_u::hwloc_osdev_attr_s osdev
-
hwloc_obj_attr_u::numanode
struct hwloc_obj_attr_u::hwloc_numanode_attr_s numanode
-
hwloc_obj_attr_u::hwloc_numanode_attr_s
NUMA node-specific Object Attributes.
Definition: hwloc.h:601
-
hwloc_obj_attr_u::hwloc_numanode_attr_s::page_types_len
unsigned page_types_len
Size of array page_types.
Definition: hwloc.h:603
-
hwloc_obj_attr_u::hwloc_numanode_attr_s::local_memory
hwloc_uint64_t local_memory
Local memory (in bytes)
Definition: hwloc.h:602
-
hwloc_obj_attr_u::hwloc_numanode_attr_s::page_types
struct hwloc_obj_attr_u::hwloc_numanode_attr_s::hwloc_memory_page_type_s * page_types
-
hwloc_obj_attr_u::hwloc_numanode_attr_s::hwloc_memory_page_type_s
Array of local memory page types, NULL if no local memory and page_types is 0.
Definition: hwloc.h:609
-
hwloc_obj_attr_u::hwloc_numanode_attr_s::hwloc_memory_page_type_s::size
hwloc_uint64_t size
Size of pages.
Definition: hwloc.h:610
-
hwloc_obj_attr_u::hwloc_numanode_attr_s::hwloc_memory_page_type_s::count
hwloc_uint64_t count
Number of pages of this size.
Definition: hwloc.h:611
-
hwloc_obj_attr_u::hwloc_cache_attr_s
Cache-specific Object Attributes.
Definition: hwloc.h:616
-
hwloc_obj_attr_u::hwloc_cache_attr_s::depth
unsigned depth
Depth of cache (e.g., L1, L2, ...etc.)
Definition: hwloc.h:618
-
hwloc_obj_attr_u::hwloc_cache_attr_s::linesize
unsigned linesize
Cache-line size in bytes. 0 if unknown.
Definition: hwloc.h:619
-
hwloc_obj_attr_u::hwloc_cache_attr_s::size
hwloc_uint64_t size
Size of cache in bytes.
Definition: hwloc.h:617
-
hwloc_obj_attr_u::hwloc_cache_attr_s::associativity
int associativity
Ways of associativity, -1 if fully associative, 0 if unknown.
Definition: hwloc.h:620
-
hwloc_obj_attr_u::hwloc_cache_attr_s::type
hwloc_obj_cache_type_t type
Cache type.
Definition: hwloc.h:622
-
hwloc_obj_attr_u::hwloc_group_attr_s
Group-specific Object Attributes.
Definition: hwloc.h:625
-
hwloc_obj_attr_u::hwloc_group_attr_s::kind
unsigned kind
Internally-used kind of group.
Definition: hwloc.h:628
-
hwloc_obj_attr_u::hwloc_group_attr_s::subkind
unsigned subkind
Internally-used subkind to distinguish different levels of groups with same kind.
Definition: hwloc.h:629
-
hwloc_obj_attr_u::hwloc_group_attr_s::depth
unsigned depth
Depth of group object. It may change if intermediate Group objects are added.
Definition: hwloc.h:626
-
hwloc_obj_attr_u::hwloc_group_attr_s::dont_merge
unsigned char dont_merge
Flag preventing groups from being automatically merged with identical parent or children.
Definition: hwloc.h:630
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s
PCI Device specific Object Attributes.
Definition: hwloc.h:633
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::revision
unsigned char revision
Definition: hwloc.h:642
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::device_id
unsigned short device_id
Definition: hwloc.h:641
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::dev
unsigned char dev
Definition: hwloc.h:639
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::subvendor_id
unsigned short subvendor_id
Definition: hwloc.h:641
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::linkspeed
float linkspeed
Definition: hwloc.h:643
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::func
unsigned char func
Definition: hwloc.h:639
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::domain
unsigned short domain
Definition: hwloc.h:635
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::vendor_id
unsigned short vendor_id
Definition: hwloc.h:641
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::bus
unsigned char bus
Definition: hwloc.h:639
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::subdevice_id
unsigned short subdevice_id
Definition: hwloc.h:641
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::class_id
unsigned short class_id
Definition: hwloc.h:640
-
hwloc_obj_attr_u::hwloc_bridge_attr_s
Bridge specific Object Attributes.
Definition: hwloc.h:646
-
hwloc_obj_attr_u::hwloc_bridge_attr_s::upstream_type
hwloc_obj_bridge_type_t upstream_type
Definition: hwloc.h:650
-
hwloc_obj_attr_u::hwloc_bridge_attr_s::domain
unsigned short domain
Definition: hwloc.h:654
-
hwloc_obj_attr_u::hwloc_bridge_attr_s::depth
unsigned depth
Definition: hwloc.h:662
-
hwloc_obj_attr_u::hwloc_bridge_attr_s::downstream
union hwloc_obj_attr_u::hwloc_bridge_attr_s::@1 downstream
-
hwloc_obj_attr_u::hwloc_bridge_attr_s::pci
struct hwloc_pcidev_attr_s pci
Definition: hwloc.h:648
-
hwloc_obj_attr_u::hwloc_bridge_attr_s::upstream
union hwloc_obj_attr_u::hwloc_bridge_attr_s::@0 upstream
-
hwloc_obj_attr_u::hwloc_bridge_attr_s::downstream_type
hwloc_obj_bridge_type_t downstream_type
Definition: hwloc.h:661
-
hwloc_obj_attr_u::hwloc_bridge_attr_s::secondary_bus
unsigned char secondary_bus
Definition: hwloc.h:658
-
hwloc_obj_attr_u::hwloc_bridge_attr_s::subordinate_bus
unsigned char subordinate_bus
Definition: hwloc.h:658
-
hwloc_obj_attr_u::hwloc_osdev_attr_s
OS Device specific Object Attributes.
Definition: hwloc.h:665
-
hwloc_obj_attr_u::hwloc_osdev_attr_s::type
hwloc_obj_osdev_type_t type
Definition: hwloc.h:666
-
hwloc_info_s
Object info.
Definition: hwloc.h:674
-
hwloc_info_s::name
char * name
Info name.
Definition: hwloc.h:675
-
hwloc_info_s::value
char * value
Info value.
Definition: hwloc.h:676
-
hwloc_topology_discovery_support
Flags describing actual discovery support for this topology.
Definition: hwloc.h:2119
-
hwloc_topology_discovery_support::numa
unsigned char numa
Detecting the number of NUMA nodes is supported.
Definition: hwloc.h:2123
-
hwloc_topology_discovery_support::disallowed_numa
unsigned char disallowed_numa
Detecting and identifying NUMA nodes that are not available to the current process is supported.
Definition: hwloc.h:2129
-
hwloc_topology_discovery_support::cpukind_efficiency
unsigned char cpukind_efficiency
Detecting the efficiency of CPU kinds is supported, see Kinds of CPU cores.
Definition: hwloc.h:2131
-
hwloc_topology_discovery_support::pu
unsigned char pu
Detecting the number of PU objects is supported.
Definition: hwloc.h:2121
-
hwloc_topology_discovery_support::numa_memory
unsigned char numa_memory
Detecting the amount of memory in NUMA nodes is supported.
Definition: hwloc.h:2125
-
hwloc_topology_discovery_support::disallowed_pu
unsigned char disallowed_pu
Detecting and identifying PU objects that are not available to the current process is supported.
Definition: hwloc.h:2127
-
hwloc_topology_cpubind_support
Flags describing actual PU binding support for this topology.
Definition: hwloc.h:2139
-
hwloc_topology_cpubind_support::get_proc_last_cpu_location
unsigned char get_proc_last_cpu_location
Definition: hwloc.h:2159
-
hwloc_topology_cpubind_support::set_thread_cpubind
unsigned char set_thread_cpubind
Definition: hwloc.h:2153
-
hwloc_topology_cpubind_support::set_thisthread_cpubind
unsigned char set_thisthread_cpubind
Definition: hwloc.h:2149
-
hwloc_topology_cpubind_support::get_thisthread_last_cpu_location
unsigned char get_thisthread_last_cpu_location
Definition: hwloc.h:2161
-
hwloc_topology_cpubind_support::get_thisproc_cpubind
unsigned char get_thisproc_cpubind
Definition: hwloc.h:2143
-
hwloc_topology_cpubind_support::get_thisthread_cpubind
unsigned char get_thisthread_cpubind
Definition: hwloc.h:2151
-
hwloc_topology_cpubind_support::get_thread_cpubind
unsigned char get_thread_cpubind
Definition: hwloc.h:2155
-
hwloc_topology_cpubind_support::set_thisproc_cpubind
unsigned char set_thisproc_cpubind
Definition: hwloc.h:2141
-
hwloc_topology_cpubind_support::set_proc_cpubind
unsigned char set_proc_cpubind
Definition: hwloc.h:2145
-
hwloc_topology_cpubind_support::get_proc_cpubind
unsigned char get_proc_cpubind
Definition: hwloc.h:2147
-
hwloc_topology_cpubind_support::get_thisproc_last_cpu_location
unsigned char get_thisproc_last_cpu_location
Definition: hwloc.h:2157
-
hwloc_topology_membind_support
Flags describing actual memory binding support for this topology.
Definition: hwloc.h:2169
-
hwloc_topology_membind_support::set_thisthread_membind
unsigned char set_thisthread_membind
Definition: hwloc.h:2179
-
hwloc_topology_membind_support::get_area_membind
unsigned char get_area_membind
Definition: hwloc.h:2185
-
hwloc_topology_membind_support::firsttouch_membind
unsigned char firsttouch_membind
Definition: hwloc.h:2189
-
hwloc_topology_membind_support::get_area_memlocation
unsigned char get_area_memlocation
Definition: hwloc.h:2199
-
hwloc_topology_membind_support::set_thisproc_membind
unsigned char set_thisproc_membind
Definition: hwloc.h:2171
-
hwloc_topology_membind_support::interleave_membind
unsigned char interleave_membind
Definition: hwloc.h:2193
-
hwloc_topology_membind_support::get_thisproc_membind
unsigned char get_thisproc_membind
Definition: hwloc.h:2173
-
hwloc_topology_membind_support::set_area_membind
unsigned char set_area_membind
Definition: hwloc.h:2183
-
hwloc_topology_membind_support::get_thisthread_membind
unsigned char get_thisthread_membind
Definition: hwloc.h:2181
-
hwloc_topology_membind_support::set_proc_membind
unsigned char set_proc_membind
Definition: hwloc.h:2175
-
hwloc_topology_membind_support::get_proc_membind
unsigned char get_proc_membind
Definition: hwloc.h:2177
-
hwloc_topology_membind_support::migrate_membind
unsigned char migrate_membind
Definition: hwloc.h:2197
-
hwloc_topology_membind_support::nexttouch_membind
unsigned char nexttouch_membind
Definition: hwloc.h:2195
-
hwloc_topology_membind_support::alloc_membind
unsigned char alloc_membind
Definition: hwloc.h:2187
-
hwloc_topology_membind_support::bind_membind
unsigned char bind_membind
Definition: hwloc.h:2191
-
hwloc_topology_misc_support
Flags describing miscellaneous features.
Definition: hwloc.h:2204
-
hwloc_topology_misc_support::imported_support
unsigned char imported_support
Definition: hwloc.h:2206
-
hwloc_topology_support
Set of flags describing actual support for this topology.
Definition: hwloc.h:2215
-
hwloc_topology_support::misc
struct hwloc_topology_misc_support * misc
Definition: hwloc.h:2219
-
hwloc_topology_support::membind
struct hwloc_topology_membind_support * membind
Definition: hwloc.h:2218
-
hwloc_topology_support::cpubind
struct hwloc_topology_cpubind_support * cpubind
Definition: hwloc.h:2217
-
hwloc_topology_support::discovery
struct hwloc_topology_discovery_support * discovery
Definition: hwloc.h:2216
-
- - - - - - - - -
-
-
helper.h
-
-
-
1 /*
-
2  * Copyright © 2009 CNRS
-
3  * Copyright © 2009-2022 Inria. All rights reserved.
-
4  * Copyright © 2009-2012 Université Bordeaux
-
5  * Copyright © 2009-2010 Cisco Systems, Inc. All rights reserved.
-
6  * See COPYING in top-level directory.
-
7  */
-
8 
-
13 #ifndef HWLOC_HELPER_H
-
14 #define HWLOC_HELPER_H
-
15 
-
16 #ifndef HWLOC_H
-
17 #error Please include the main hwloc.h instead
-
18 #endif
-
19 
-
20 #include <stdlib.h>
-
21 #include <errno.h>
-
22 
-
23 
-
24 #ifdef __cplusplus
-
25 extern "C" {
-
26 #endif
-
27 
-
28 
-
41 static __hwloc_inline hwloc_obj_t
-
42 hwloc_get_first_largest_obj_inside_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t set)
-
43 {
-
44  hwloc_obj_t obj = hwloc_get_root_obj(topology);
-
45  if (!hwloc_bitmap_intersects(obj->cpuset, set))
-
46  return NULL;
-
47  while (!hwloc_bitmap_isincluded(obj->cpuset, set)) {
-
48  /* while the object intersects without being included, look at its children */
-
49  hwloc_obj_t child = obj->first_child;
-
50  while (child) {
-
51  if (hwloc_bitmap_intersects(child->cpuset, set))
-
52  break;
-
53  child = child->next_sibling;
-
54  }
-
55  if (!child)
-
56  /* no child intersects, return their father */
-
57  return obj;
-
58  /* found one intersecting child, look at its children */
-
59  obj = child;
-
60  }
-
61  /* obj is included, return it */
-
62  return obj;
-
63 }
-
64 
-
69 HWLOC_DECLSPEC int hwloc_get_largest_objs_inside_cpuset (hwloc_topology_t topology, hwloc_const_cpuset_t set,
-
70  hwloc_obj_t * __hwloc_restrict objs, int max);
-
71 
-
84 static __hwloc_inline hwloc_obj_t
-
85 hwloc_get_next_obj_inside_cpuset_by_depth (hwloc_topology_t topology, hwloc_const_cpuset_t set,
-
86  int depth, hwloc_obj_t prev)
-
87 {
-
88  hwloc_obj_t next = hwloc_get_next_obj_by_depth(topology, depth, prev);
-
89  if (!next)
-
90  return NULL;
-
91  while (next && (hwloc_bitmap_iszero(next->cpuset) || !hwloc_bitmap_isincluded(next->cpuset, set)))
-
92  next = next->next_cousin;
-
93  return next;
-
94 }
-
95 
-
108 static __hwloc_inline hwloc_obj_t
-
109 hwloc_get_next_obj_inside_cpuset_by_type (hwloc_topology_t topology, hwloc_const_cpuset_t set,
-
110  hwloc_obj_type_t type, hwloc_obj_t prev)
-
111 {
-
112  int depth = hwloc_get_type_depth(topology, type);
-
113  if (depth == HWLOC_TYPE_DEPTH_UNKNOWN || depth == HWLOC_TYPE_DEPTH_MULTIPLE)
-
114  return NULL;
-
115  return hwloc_get_next_obj_inside_cpuset_by_depth(topology, set, depth, prev);
-
116 }
-
117 
-
126 static __hwloc_inline hwloc_obj_t
-
127 hwloc_get_obj_inside_cpuset_by_depth (hwloc_topology_t topology, hwloc_const_cpuset_t set,
-
128  int depth, unsigned idx) __hwloc_attribute_pure;
-
129 static __hwloc_inline hwloc_obj_t
-
130 hwloc_get_obj_inside_cpuset_by_depth (hwloc_topology_t topology, hwloc_const_cpuset_t set,
-
131  int depth, unsigned idx)
-
132 {
-
133  hwloc_obj_t obj = hwloc_get_obj_by_depth (topology, depth, 0);
-
134  unsigned count = 0;
-
135  if (!obj)
-
136  return NULL;
-
137  while (obj) {
-
138  if (!hwloc_bitmap_iszero(obj->cpuset) && hwloc_bitmap_isincluded(obj->cpuset, set)) {
-
139  if (count == idx)
-
140  return obj;
-
141  count++;
-
142  }
-
143  obj = obj->next_cousin;
-
144  }
-
145  return NULL;
-
146 }
-
147 
-
160 static __hwloc_inline hwloc_obj_t
-
161 hwloc_get_obj_inside_cpuset_by_type (hwloc_topology_t topology, hwloc_const_cpuset_t set,
-
162  hwloc_obj_type_t type, unsigned idx) __hwloc_attribute_pure;
-
163 static __hwloc_inline hwloc_obj_t
-
164 hwloc_get_obj_inside_cpuset_by_type (hwloc_topology_t topology, hwloc_const_cpuset_t set,
-
165  hwloc_obj_type_t type, unsigned idx)
-
166 {
-
167  int depth = hwloc_get_type_depth(topology, type);
-
168  if (depth == HWLOC_TYPE_DEPTH_UNKNOWN || depth == HWLOC_TYPE_DEPTH_MULTIPLE)
-
169  return NULL;
-
170  return hwloc_get_obj_inside_cpuset_by_depth(topology, set, depth, idx);
-
171 }
-
172 
-
181 static __hwloc_inline unsigned
-
182 hwloc_get_nbobjs_inside_cpuset_by_depth (hwloc_topology_t topology, hwloc_const_cpuset_t set,
-
183  int depth) __hwloc_attribute_pure;
-
184 static __hwloc_inline unsigned
-
185 hwloc_get_nbobjs_inside_cpuset_by_depth (hwloc_topology_t topology, hwloc_const_cpuset_t set,
-
186  int depth)
-
187 {
-
188  hwloc_obj_t obj = hwloc_get_obj_by_depth (topology, depth, 0);
-
189  unsigned count = 0;
-
190  if (!obj)
-
191  return 0;
-
192  while (obj) {
-
193  if (!hwloc_bitmap_iszero(obj->cpuset) && hwloc_bitmap_isincluded(obj->cpuset, set))
-
194  count++;
-
195  obj = obj->next_cousin;
-
196  }
-
197  return count;
-
198 }
-
199 
-
212 static __hwloc_inline int
-
213 hwloc_get_nbobjs_inside_cpuset_by_type (hwloc_topology_t topology, hwloc_const_cpuset_t set,
-
214  hwloc_obj_type_t type) __hwloc_attribute_pure;
-
215 static __hwloc_inline int
-
216 hwloc_get_nbobjs_inside_cpuset_by_type (hwloc_topology_t topology, hwloc_const_cpuset_t set,
-
217  hwloc_obj_type_t type)
-
218 {
-
219  int depth = hwloc_get_type_depth(topology, type);
-
220  if (depth == HWLOC_TYPE_DEPTH_UNKNOWN)
-
221  return 0;
-
222  if (depth == HWLOC_TYPE_DEPTH_MULTIPLE)
-
223  return -1; /* FIXME: agregate nbobjs from different levels? */
-
224  return (int) hwloc_get_nbobjs_inside_cpuset_by_depth(topology, set, depth);
-
225 }
-
226 
-
240 static __hwloc_inline int
-
241 hwloc_get_obj_index_inside_cpuset (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_const_cpuset_t set,
-
242  hwloc_obj_t obj) __hwloc_attribute_pure;
-
243 static __hwloc_inline int
-
244 hwloc_get_obj_index_inside_cpuset (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_const_cpuset_t set,
-
245  hwloc_obj_t obj)
-
246 {
-
247  int idx = 0;
-
248  if (!hwloc_bitmap_isincluded(obj->cpuset, set))
-
249  return -1;
-
250  /* count how many objects are inside the cpuset on the way from us to the beginning of the level */
-
251  while ((obj = obj->prev_cousin) != NULL)
-
252  if (!hwloc_bitmap_iszero(obj->cpuset) && hwloc_bitmap_isincluded(obj->cpuset, set))
-
253  idx++;
-
254  return idx;
-
255 }
-
256 
-
271 static __hwloc_inline hwloc_obj_t
-
272 hwloc_get_child_covering_cpuset (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_const_cpuset_t set,
-
273  hwloc_obj_t parent) __hwloc_attribute_pure;
-
274 static __hwloc_inline hwloc_obj_t
-
275 hwloc_get_child_covering_cpuset (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_const_cpuset_t set,
-
276  hwloc_obj_t parent)
-
277 {
-
278  hwloc_obj_t child;
-
279  if (hwloc_bitmap_iszero(set))
-
280  return NULL;
-
281  child = parent->first_child;
-
282  while (child) {
-
283  if (child->cpuset && hwloc_bitmap_isincluded(set, child->cpuset))
-
284  return child;
-
285  child = child->next_sibling;
-
286  }
-
287  return NULL;
-
288 }
-
289 
-
294 static __hwloc_inline hwloc_obj_t
-
295 hwloc_get_obj_covering_cpuset (hwloc_topology_t topology, hwloc_const_cpuset_t set) __hwloc_attribute_pure;
-
296 static __hwloc_inline hwloc_obj_t
-
297 hwloc_get_obj_covering_cpuset (hwloc_topology_t topology, hwloc_const_cpuset_t set)
-
298 {
-
299  struct hwloc_obj *current = hwloc_get_root_obj(topology);
-
300  if (hwloc_bitmap_iszero(set) || !hwloc_bitmap_isincluded(set, current->cpuset))
-
301  return NULL;
-
302  while (1) {
-
303  hwloc_obj_t child = hwloc_get_child_covering_cpuset(topology, set, current);
-
304  if (!child)
-
305  return current;
-
306  current = child;
-
307  }
-
308 }
-
309 
-
320 static __hwloc_inline hwloc_obj_t
-
321 hwloc_get_next_obj_covering_cpuset_by_depth(hwloc_topology_t topology, hwloc_const_cpuset_t set,
-
322  int depth, hwloc_obj_t prev)
-
323 {
-
324  hwloc_obj_t next = hwloc_get_next_obj_by_depth(topology, depth, prev);
-
325  if (!next)
-
326  return NULL;
-
327  while (next && !hwloc_bitmap_intersects(set, next->cpuset))
-
328  next = next->next_cousin;
-
329  return next;
-
330 }
-
331 
-
347 static __hwloc_inline hwloc_obj_t
-
348 hwloc_get_next_obj_covering_cpuset_by_type(hwloc_topology_t topology, hwloc_const_cpuset_t set,
-
349  hwloc_obj_type_t type, hwloc_obj_t prev)
-
350 {
-
351  int depth = hwloc_get_type_depth(topology, type);
-
352  if (depth == HWLOC_TYPE_DEPTH_UNKNOWN || depth == HWLOC_TYPE_DEPTH_MULTIPLE)
-
353  return NULL;
-
354  return hwloc_get_next_obj_covering_cpuset_by_depth(topology, set, depth, prev);
-
355 }
-
356 
-
377 static __hwloc_inline hwloc_obj_t
-
378 hwloc_get_ancestor_obj_by_depth (hwloc_topology_t topology __hwloc_attribute_unused, int depth, hwloc_obj_t obj) __hwloc_attribute_pure;
-
379 static __hwloc_inline hwloc_obj_t
-
380 hwloc_get_ancestor_obj_by_depth (hwloc_topology_t topology __hwloc_attribute_unused, int depth, hwloc_obj_t obj)
-
381 {
-
382  hwloc_obj_t ancestor = obj;
-
383  if (obj->depth < depth)
-
384  return NULL;
-
385  while (ancestor && ancestor->depth > depth)
-
386  ancestor = ancestor->parent;
-
387  return ancestor;
-
388 }
-
389 
-
397 static __hwloc_inline hwloc_obj_t
-
398 hwloc_get_ancestor_obj_by_type (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_obj_type_t type, hwloc_obj_t obj) __hwloc_attribute_pure;
-
399 static __hwloc_inline hwloc_obj_t
-
400 hwloc_get_ancestor_obj_by_type (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_obj_type_t type, hwloc_obj_t obj)
-
401 {
-
402  hwloc_obj_t ancestor = obj->parent;
-
403  while (ancestor && ancestor->type != type)
-
404  ancestor = ancestor->parent;
-
405  return ancestor;
-
406 }
-
407 
-
409 static __hwloc_inline hwloc_obj_t
-
410 hwloc_get_common_ancestor_obj (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_obj_t obj1, hwloc_obj_t obj2) __hwloc_attribute_pure;
-
411 static __hwloc_inline hwloc_obj_t
-
412 hwloc_get_common_ancestor_obj (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_obj_t obj1, hwloc_obj_t obj2)
-
413 {
-
414  /* the loop isn't so easy since intermediate ancestors may have
-
415  * different depth, causing us to alternate between using obj1->parent
-
416  * and obj2->parent. Also, even if at some point we find ancestors of
-
417  * of the same depth, their ancestors may have different depth again.
-
418  */
-
419  while (obj1 != obj2) {
-
420  while (obj1->depth > obj2->depth)
-
421  obj1 = obj1->parent;
-
422  while (obj2->depth > obj1->depth)
-
423  obj2 = obj2->parent;
-
424  if (obj1 != obj2 && obj1->depth == obj2->depth) {
-
425  obj1 = obj1->parent;
-
426  obj2 = obj2->parent;
-
427  }
-
428  }
-
429  return obj1;
-
430 }
-
431 
-
437 static __hwloc_inline int
-
438 hwloc_obj_is_in_subtree (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_obj_t obj, hwloc_obj_t subtree_root) __hwloc_attribute_pure;
-
439 static __hwloc_inline int
-
440 hwloc_obj_is_in_subtree (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_obj_t obj, hwloc_obj_t subtree_root)
-
441 {
-
442  return obj->cpuset && subtree_root->cpuset && hwloc_bitmap_isincluded(obj->cpuset, subtree_root->cpuset);
-
443 }
-
444 
-
455 static __hwloc_inline hwloc_obj_t
-
456 hwloc_get_next_child (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_obj_t parent, hwloc_obj_t prev)
-
457 {
-
458  hwloc_obj_t obj;
-
459  int state = 0;
-
460  if (prev) {
-
461  if (prev->type == HWLOC_OBJ_MISC)
-
462  state = 3;
-
463  else if (prev->type == HWLOC_OBJ_BRIDGE || prev->type == HWLOC_OBJ_PCI_DEVICE || prev->type == HWLOC_OBJ_OS_DEVICE)
-
464  state = 2;
-
465  else if (prev->type == HWLOC_OBJ_NUMANODE)
-
466  state = 1;
-
467  obj = prev->next_sibling;
-
468  } else {
-
469  obj = parent->first_child;
-
470  }
-
471  if (!obj && state == 0) {
-
472  obj = parent->memory_first_child;
-
473  state = 1;
-
474  }
-
475  if (!obj && state == 1) {
-
476  obj = parent->io_first_child;
-
477  state = 2;
-
478  }
-
479  if (!obj && state == 2) {
-
480  obj = parent->misc_first_child;
-
481  state = 3;
-
482  }
-
483  return obj;
-
484 }
-
485 
-
512 HWLOC_DECLSPEC int
-
513 hwloc_obj_type_is_normal(hwloc_obj_type_t type);
-
514 
-
523 HWLOC_DECLSPEC int
-
524 hwloc_obj_type_is_io(hwloc_obj_type_t type);
-
525 
-
534 HWLOC_DECLSPEC int
-
535 hwloc_obj_type_is_memory(hwloc_obj_type_t type);
-
536 
-
543 HWLOC_DECLSPEC int
-
544 hwloc_obj_type_is_cache(hwloc_obj_type_t type);
-
545 
-
552 HWLOC_DECLSPEC int
-
553 hwloc_obj_type_is_dcache(hwloc_obj_type_t type);
-
554 
-
561 HWLOC_DECLSPEC int
-
562 hwloc_obj_type_is_icache(hwloc_obj_type_t type);
-
563 
-
593 static __hwloc_inline int
-
594 hwloc_get_cache_type_depth (hwloc_topology_t topology,
-
595  unsigned cachelevel, hwloc_obj_cache_type_t cachetype)
-
596 {
-
597  int depth;
-
598  int found = HWLOC_TYPE_DEPTH_UNKNOWN;
-
599  for (depth=0; ; depth++) {
-
600  hwloc_obj_t obj = hwloc_get_obj_by_depth(topology, depth, 0);
-
601  if (!obj)
-
602  break;
-
603  if (!hwloc_obj_type_is_dcache(obj->type) || obj->attr->cache.depth != cachelevel)
-
604  /* doesn't match, try next depth */
-
605  continue;
-
606  if (cachetype == (hwloc_obj_cache_type_t) -1) {
-
607  if (found != HWLOC_TYPE_DEPTH_UNKNOWN) {
-
608  /* second match, return MULTIPLE */
-
609  return HWLOC_TYPE_DEPTH_MULTIPLE;
-
610  }
-
611  /* first match, mark it as found */
-
612  found = depth;
-
613  continue;
-
614  }
-
615  if (obj->attr->cache.type == cachetype || obj->attr->cache.type == HWLOC_OBJ_CACHE_UNIFIED)
-
616  /* exact match (either unified is alone, or we match instruction or data), return immediately */
-
617  return depth;
-
618  }
-
619  /* went to the bottom, return what we found */
-
620  return found;
-
621 }
-
622 
-
627 static __hwloc_inline hwloc_obj_t
-
628 hwloc_get_cache_covering_cpuset (hwloc_topology_t topology, hwloc_const_cpuset_t set) __hwloc_attribute_pure;
-
629 static __hwloc_inline hwloc_obj_t
-
630 hwloc_get_cache_covering_cpuset (hwloc_topology_t topology, hwloc_const_cpuset_t set)
-
631 {
-
632  hwloc_obj_t current = hwloc_get_obj_covering_cpuset(topology, set);
-
633  while (current) {
-
634  if (hwloc_obj_type_is_dcache(current->type))
-
635  return current;
-
636  current = current->parent;
-
637  }
-
638  return NULL;
-
639 }
-
640 
-
645 static __hwloc_inline hwloc_obj_t
-
646 hwloc_get_shared_cache_covering_obj (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_obj_t obj) __hwloc_attribute_pure;
-
647 static __hwloc_inline hwloc_obj_t
-
648 hwloc_get_shared_cache_covering_obj (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_obj_t obj)
-
649 {
-
650  hwloc_obj_t current = obj->parent;
-
651  if (!obj->cpuset)
-
652  return NULL;
-
653  while (current) {
-
654  if (!hwloc_bitmap_isequal(current->cpuset, obj->cpuset)
-
655  && hwloc_obj_type_is_dcache(current->type))
-
656  return current;
-
657  current = current->parent;
-
658  }
-
659  return NULL;
-
660 }
-
661 
-
691 HWLOC_DECLSPEC int hwloc_bitmap_singlify_per_core(hwloc_topology_t topology, hwloc_bitmap_t cpuset, unsigned which);
-
692 
-
702 static __hwloc_inline hwloc_obj_t
-
703 hwloc_get_pu_obj_by_os_index(hwloc_topology_t topology, unsigned os_index) __hwloc_attribute_pure;
-
704 static __hwloc_inline hwloc_obj_t
-
705 hwloc_get_pu_obj_by_os_index(hwloc_topology_t topology, unsigned os_index)
-
706 {
-
707  hwloc_obj_t obj = NULL;
-
708  while ((obj = hwloc_get_next_obj_by_type(topology, HWLOC_OBJ_PU, obj)) != NULL)
-
709  if (obj->os_index == os_index)
-
710  return obj;
-
711  return NULL;
-
712 }
-
713 
-
723 static __hwloc_inline hwloc_obj_t
-
724 hwloc_get_numanode_obj_by_os_index(hwloc_topology_t topology, unsigned os_index) __hwloc_attribute_pure;
-
725 static __hwloc_inline hwloc_obj_t
-
726 hwloc_get_numanode_obj_by_os_index(hwloc_topology_t topology, unsigned os_index)
-
727 {
-
728  hwloc_obj_t obj = NULL;
-
729  while ((obj = hwloc_get_next_obj_by_type(topology, HWLOC_OBJ_NUMANODE, obj)) != NULL)
-
730  if (obj->os_index == os_index)
-
731  return obj;
-
732  return NULL;
-
733 }
-
734 
-
746 /* TODO: rather provide an iterator? Provide a way to know how much should be allocated? By returning the total number of objects instead? */
-
747 HWLOC_DECLSPEC unsigned hwloc_get_closest_objs (hwloc_topology_t topology, hwloc_obj_t src, hwloc_obj_t * __hwloc_restrict objs, unsigned max);
-
748 
-
761 static __hwloc_inline hwloc_obj_t
-
762 hwloc_get_obj_below_by_type (hwloc_topology_t topology,
-
763  hwloc_obj_type_t type1, unsigned idx1,
-
764  hwloc_obj_type_t type2, unsigned idx2) __hwloc_attribute_pure;
-
765 static __hwloc_inline hwloc_obj_t
-
766 hwloc_get_obj_below_by_type (hwloc_topology_t topology,
-
767  hwloc_obj_type_t type1, unsigned idx1,
-
768  hwloc_obj_type_t type2, unsigned idx2)
-
769 {
-
770  hwloc_obj_t obj;
-
771  obj = hwloc_get_obj_by_type (topology, type1, idx1);
-
772  if (!obj)
-
773  return NULL;
-
774  return hwloc_get_obj_inside_cpuset_by_type(topology, obj->cpuset, type2, idx2);
-
775 }
-
776 
-
795 static __hwloc_inline hwloc_obj_t
-
796 hwloc_get_obj_below_array_by_type (hwloc_topology_t topology, int nr, hwloc_obj_type_t *typev, unsigned *idxv) __hwloc_attribute_pure;
-
797 static __hwloc_inline hwloc_obj_t
-
798 hwloc_get_obj_below_array_by_type (hwloc_topology_t topology, int nr, hwloc_obj_type_t *typev, unsigned *idxv)
-
799 {
-
800  hwloc_obj_t obj = hwloc_get_root_obj(topology);
-
801  int i;
-
802  for(i=0; i<nr; i++) {
-
803  if (!obj)
-
804  return NULL;
-
805  obj = hwloc_get_obj_inside_cpuset_by_type(topology, obj->cpuset, typev[i], idxv[i]);
-
806  }
-
807  return obj;
-
808 }
-
809 
-
848 HWLOC_DECLSPEC hwloc_obj_t
-
849 hwloc_get_obj_with_same_locality(hwloc_topology_t topology, hwloc_obj_t src,
-
850  hwloc_obj_type_t type, const char *subtype, const char *nameprefix,
-
851  unsigned long flags);
-
852 
-
863 enum hwloc_distrib_flags_e {
-
867  HWLOC_DISTRIB_FLAG_REVERSE = (1UL<<0)
-
868 };
-
869 
-
890 static __hwloc_inline int
-
891 hwloc_distrib(hwloc_topology_t topology,
-
892  hwloc_obj_t *roots, unsigned n_roots,
-
893  hwloc_cpuset_t *set,
-
894  unsigned n,
-
895  int until, unsigned long flags)
-
896 {
-
897  unsigned i;
-
898  unsigned tot_weight;
-
899  unsigned given, givenweight;
-
900  hwloc_cpuset_t *cpusetp = set;
-
901 
-
902  if (flags & ~HWLOC_DISTRIB_FLAG_REVERSE) {
-
903  errno = EINVAL;
-
904  return -1;
-
905  }
-
906 
-
907  tot_weight = 0;
-
908  for (i = 0; i < n_roots; i++)
-
909  tot_weight += (unsigned) hwloc_bitmap_weight(roots[i]->cpuset);
-
910 
-
911  for (i = 0, given = 0, givenweight = 0; i < n_roots; i++) {
-
912  unsigned chunk, weight;
-
913  hwloc_obj_t root = roots[flags & HWLOC_DISTRIB_FLAG_REVERSE ? n_roots-1-i : i];
-
914  hwloc_cpuset_t cpuset = root->cpuset;
-
915  while (!hwloc_obj_type_is_normal(root->type))
-
916  /* If memory/io/misc, walk up to normal parent */
-
917  root = root->parent;
-
918  weight = (unsigned) hwloc_bitmap_weight(cpuset);
-
919  if (!weight)
-
920  continue;
-
921  /* Give to root a chunk proportional to its weight.
-
922  * If previous chunks got rounded-up, we may get a bit less. */
-
923  chunk = (( (givenweight+weight) * n + tot_weight-1) / tot_weight)
-
924  - (( givenweight * n + tot_weight-1) / tot_weight);
-
925  if (!root->arity || chunk <= 1 || root->depth >= until) {
-
926  /* We can't split any more, put everything there. */
-
927  if (chunk) {
-
928  /* Fill cpusets with ours */
-
929  unsigned j;
-
930  for (j=0; j < chunk; j++)
-
931  cpusetp[j] = hwloc_bitmap_dup(cpuset);
-
932  } else {
-
933  /* We got no chunk, just merge our cpuset to a previous one
-
934  * (the first chunk cannot be empty)
-
935  * so that this root doesn't get ignored.
-
936  */
-
937  assert(given);
-
938  hwloc_bitmap_or(cpusetp[-1], cpusetp[-1], cpuset);
-
939  }
-
940  } else {
-
941  /* Still more to distribute, recurse into children */
-
942  hwloc_distrib(topology, root->children, root->arity, cpusetp, chunk, until, flags);
-
943  }
-
944  cpusetp += chunk;
-
945  given += chunk;
-
946  givenweight += weight;
-
947  }
-
948 
-
949  return 0;
-
950 }
-
951 
-
969 HWLOC_DECLSPEC hwloc_const_cpuset_t
-
970 hwloc_topology_get_complete_cpuset(hwloc_topology_t topology) __hwloc_attribute_pure;
-
971 
-
983 HWLOC_DECLSPEC hwloc_const_cpuset_t
-
984 hwloc_topology_get_topology_cpuset(hwloc_topology_t topology) __hwloc_attribute_pure;
-
985 
-
1002 HWLOC_DECLSPEC hwloc_const_cpuset_t
-
1003 hwloc_topology_get_allowed_cpuset(hwloc_topology_t topology) __hwloc_attribute_pure;
-
1004 
-
1014 HWLOC_DECLSPEC hwloc_const_nodeset_t
-
1015 hwloc_topology_get_complete_nodeset(hwloc_topology_t topology) __hwloc_attribute_pure;
-
1016 
-
1028 HWLOC_DECLSPEC hwloc_const_nodeset_t
-
1029 hwloc_topology_get_topology_nodeset(hwloc_topology_t topology) __hwloc_attribute_pure;
-
1030 
-
1047 HWLOC_DECLSPEC hwloc_const_nodeset_t
-
1048 hwloc_topology_get_allowed_nodeset(hwloc_topology_t topology) __hwloc_attribute_pure;
-
1049 
-
1070 static __hwloc_inline int
-
1071 hwloc_cpuset_to_nodeset(hwloc_topology_t topology, hwloc_const_cpuset_t _cpuset, hwloc_nodeset_t nodeset)
-
1072 {
-
1073  int depth = hwloc_get_type_depth(topology, HWLOC_OBJ_NUMANODE);
-
1074  hwloc_obj_t obj = NULL;
-
1075  assert(depth != HWLOC_TYPE_DEPTH_UNKNOWN);
-
1076  hwloc_bitmap_zero(nodeset);
-
1077  while ((obj = hwloc_get_next_obj_covering_cpuset_by_depth(topology, _cpuset, depth, obj)) != NULL)
-
1078  if (hwloc_bitmap_set(nodeset, obj->os_index) < 0)
-
1079  return -1;
-
1080  return 0;
-
1081 }
-
1082 
-
1094 static __hwloc_inline int
-
1095 hwloc_cpuset_from_nodeset(hwloc_topology_t topology, hwloc_cpuset_t _cpuset, hwloc_const_nodeset_t nodeset)
-
1096 {
-
1097  int depth = hwloc_get_type_depth(topology, HWLOC_OBJ_NUMANODE);
-
1098  hwloc_obj_t obj = NULL;
-
1099  assert(depth != HWLOC_TYPE_DEPTH_UNKNOWN);
-
1100  hwloc_bitmap_zero(_cpuset);
-
1101  while ((obj = hwloc_get_next_obj_by_depth(topology, depth, obj)) != NULL) {
-
1102  if (hwloc_bitmap_isset(nodeset, obj->os_index))
-
1103  /* no need to check obj->cpuset because objects in levels always have a cpuset */
-
1104  if (hwloc_bitmap_or(_cpuset, _cpuset, obj->cpuset) < 0)
-
1105  return -1;
-
1106  }
-
1107  return 0;
-
1108 }
-
1109 
-
1129 static __hwloc_inline hwloc_obj_t
-
1130 hwloc_get_non_io_ancestor_obj(hwloc_topology_t topology __hwloc_attribute_unused,
-
1131  hwloc_obj_t ioobj)
-
1132 {
-
1133  hwloc_obj_t obj = ioobj;
-
1134  while (obj && !obj->cpuset) {
-
1135  obj = obj->parent;
-
1136  }
-
1137  return obj;
-
1138 }
-
1139 
-
1144 static __hwloc_inline hwloc_obj_t
-
1145 hwloc_get_next_pcidev(hwloc_topology_t topology, hwloc_obj_t prev)
-
1146 {
-
1147  return hwloc_get_next_obj_by_type(topology, HWLOC_OBJ_PCI_DEVICE, prev);
-
1148 }
-
1149 
-
1153 static __hwloc_inline hwloc_obj_t
-
1154 hwloc_get_pcidev_by_busid(hwloc_topology_t topology,
-
1155  unsigned domain, unsigned bus, unsigned dev, unsigned func)
-
1156 {
-
1157  hwloc_obj_t obj = NULL;
-
1158  while ((obj = hwloc_get_next_pcidev(topology, obj)) != NULL) {
-
1159  if (obj->attr->pcidev.domain == domain
-
1160  && obj->attr->pcidev.bus == bus
-
1161  && obj->attr->pcidev.dev == dev
-
1162  && obj->attr->pcidev.func == func)
-
1163  return obj;
-
1164  }
-
1165  return NULL;
-
1166 }
-
1167 
-
1171 static __hwloc_inline hwloc_obj_t
-
1172 hwloc_get_pcidev_by_busidstring(hwloc_topology_t topology, const char *busid)
-
1173 {
-
1174  unsigned domain = 0; /* default */
-
1175  unsigned bus, dev, func;
-
1176 
-
1177  if (sscanf(busid, "%x:%x.%x", &bus, &dev, &func) != 3
-
1178  && sscanf(busid, "%x:%x:%x.%x", &domain, &bus, &dev, &func) != 4) {
-
1179  errno = EINVAL;
-
1180  return NULL;
-
1181  }
-
1182 
-
1183  return hwloc_get_pcidev_by_busid(topology, domain, bus, dev, func);
-
1184 }
-
1185 
-
1190 static __hwloc_inline hwloc_obj_t
-
1191 hwloc_get_next_osdev(hwloc_topology_t topology, hwloc_obj_t prev)
-
1192 {
-
1193  return hwloc_get_next_obj_by_type(topology, HWLOC_OBJ_OS_DEVICE, prev);
-
1194 }
-
1195 
-
1200 static __hwloc_inline hwloc_obj_t
-
1201 hwloc_get_next_bridge(hwloc_topology_t topology, hwloc_obj_t prev)
-
1202 {
-
1203  return hwloc_get_next_obj_by_type(topology, HWLOC_OBJ_BRIDGE, prev);
-
1204 }
-
1205 
-
1206 /* \brief Checks whether a given bridge covers a given PCI bus.
-
1207  */
-
1208 static __hwloc_inline int
-
1209 hwloc_bridge_covers_pcibus(hwloc_obj_t bridge,
-
1210  unsigned domain, unsigned bus)
-
1211 {
-
1212  return bridge->type == HWLOC_OBJ_BRIDGE
-
1213  && bridge->attr->bridge.downstream_type == HWLOC_OBJ_BRIDGE_PCI
-
1214  && bridge->attr->bridge.downstream.pci.domain == domain
-
1215  && bridge->attr->bridge.downstream.pci.secondary_bus <= bus
-
1216  && bridge->attr->bridge.downstream.pci.subordinate_bus >= bus;
-
1217 }
-
1218 
-
1223 #ifdef __cplusplus
-
1224 } /* extern "C" */
-
1225 #endif
-
1226 
-
1227 
-
1228 #endif /* HWLOC_HELPER_H */
-
hwloc_const_cpuset_t
hwloc_const_bitmap_t hwloc_const_cpuset_t
A non-modifiable hwloc_cpuset_t.
Definition: hwloc.h:142
-
hwloc_const_nodeset_t
hwloc_const_bitmap_t hwloc_const_nodeset_t
A non-modifiable hwloc_nodeset_t.
Definition: hwloc.h:160
-
hwloc_nodeset_t
hwloc_bitmap_t hwloc_nodeset_t
A node set is a bitmap whose bits are set according to NUMA memory node physical OS indexes.
Definition: hwloc.h:157
-
hwloc_cpuset_t
hwloc_bitmap_t hwloc_cpuset_t
A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
Definition: hwloc.h:140
-
hwloc_obj_cache_type_t
enum hwloc_obj_cache_type_e hwloc_obj_cache_type_t
Cache type.
-
hwloc_obj_type_t
hwloc_obj_type_t
Type of topology object.
Definition: hwloc.h:176
-
HWLOC_OBJ_BRIDGE_PCI
@ HWLOC_OBJ_BRIDGE_PCI
PCI-side of a bridge.
Definition: hwloc.h:335
-
HWLOC_OBJ_CACHE_UNIFIED
@ HWLOC_OBJ_CACHE_UNIFIED
Unified cache.
Definition: hwloc.h:327
-
HWLOC_OBJ_MISC
@ HWLOC_OBJ_MISC
Miscellaneous objects (filtered out by default). Objects without particular meaning,...
Definition: hwloc.h:290
-
HWLOC_OBJ_OS_DEVICE
@ HWLOC_OBJ_OS_DEVICE
Operating system device (filtered out by default).
Definition: hwloc.h:279
-
HWLOC_OBJ_PCI_DEVICE
@ HWLOC_OBJ_PCI_DEVICE
PCI device (filtered out by default).
Definition: hwloc.h:269
-
HWLOC_OBJ_BRIDGE
@ HWLOC_OBJ_BRIDGE
Bridge (filtered out by default). Any bridge (or PCI switch) that connects the host or an I/O bus,...
Definition: hwloc.h:257
-
HWLOC_OBJ_NUMANODE
@ HWLOC_OBJ_NUMANODE
NUMA node. An object that contains memory that is directly and byte-accessible to the host processors...
Definition: hwloc.h:236
-
HWLOC_OBJ_PU
@ HWLOC_OBJ_PU
Processing Unit, or (Logical) Processor. An execution unit (may share a core with some other logical ...
Definition: hwloc.h:201
-
hwloc_topology_t
struct hwloc_topology * hwloc_topology_t
Topology context.
Definition: hwloc.h:692
-
hwloc_get_root_obj
static hwloc_obj_t hwloc_get_root_obj(hwloc_topology_t topology)
Returns the top-object of the topology-tree.
-
hwloc_get_obj_by_depth
hwloc_obj_t hwloc_get_obj_by_depth(hwloc_topology_t topology, int depth, unsigned idx)
Returns the topology object at logical index idx from depth depth.
-
hwloc_get_obj_by_type
static hwloc_obj_t hwloc_get_obj_by_type(hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx)
Returns the topology object at logical index idx with type type.
-
hwloc_get_next_obj_by_type
static hwloc_obj_t hwloc_get_next_obj_by_type(hwloc_topology_t topology, hwloc_obj_type_t type, hwloc_obj_t prev)
Returns the next object of type type.
-
hwloc_get_type_depth
int hwloc_get_type_depth(hwloc_topology_t topology, hwloc_obj_type_t type)
Returns the depth of objects of type type.
-
hwloc_get_next_obj_by_depth
static hwloc_obj_t hwloc_get_next_obj_by_depth(hwloc_topology_t topology, int depth, hwloc_obj_t prev)
Returns the next object at depth depth.
-
HWLOC_TYPE_DEPTH_UNKNOWN
@ HWLOC_TYPE_DEPTH_UNKNOWN
No object of given type exists in the topology.
Definition: hwloc.h:822
-
HWLOC_TYPE_DEPTH_MULTIPLE
@ HWLOC_TYPE_DEPTH_MULTIPLE
Objects of given type exist at different depth in the topology (only for Groups).
Definition: hwloc.h:823
-
hwloc_get_nbobjs_inside_cpuset_by_type
static int hwloc_get_nbobjs_inside_cpuset_by_type(hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_type_t type)
Return the number of objects of type type included in CPU set set.
Definition: helper.h:216
-
hwloc_get_obj_inside_cpuset_by_type
static hwloc_obj_t hwloc_get_obj_inside_cpuset_by_type(hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_type_t type, unsigned idx)
Return the idx -th object of type type included in CPU set set.
Definition: helper.h:164
-
hwloc_get_largest_objs_inside_cpuset
int hwloc_get_largest_objs_inside_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_t *restrict objs, int max)
Get the set of largest objects covering exactly a given cpuset set.
-
hwloc_get_obj_index_inside_cpuset
static int hwloc_get_obj_index_inside_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_t obj)
Return the logical index among the objects included in CPU set set.
Definition: helper.h:244
-
hwloc_get_first_largest_obj_inside_cpuset
static hwloc_obj_t hwloc_get_first_largest_obj_inside_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t set)
Get the first largest object included in the given cpuset set.
Definition: helper.h:42
-
hwloc_get_next_obj_inside_cpuset_by_depth
static hwloc_obj_t hwloc_get_next_obj_inside_cpuset_by_depth(hwloc_topology_t topology, hwloc_const_cpuset_t set, int depth, hwloc_obj_t prev)
Return the next object at depth depth included in CPU set set.
Definition: helper.h:85
-
hwloc_get_nbobjs_inside_cpuset_by_depth
static unsigned hwloc_get_nbobjs_inside_cpuset_by_depth(hwloc_topology_t topology, hwloc_const_cpuset_t set, int depth)
Return the number of objects at depth depth included in CPU set set.
Definition: helper.h:185
-
hwloc_get_obj_inside_cpuset_by_depth
static hwloc_obj_t hwloc_get_obj_inside_cpuset_by_depth(hwloc_topology_t topology, hwloc_const_cpuset_t set, int depth, unsigned idx)
Return the (logically) idx -th object at depth depth included in CPU set set.
Definition: helper.h:130
-
hwloc_get_next_obj_inside_cpuset_by_type
static hwloc_obj_t hwloc_get_next_obj_inside_cpuset_by_type(hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_type_t type, hwloc_obj_t prev)
Return the next object of type type included in CPU set set.
Definition: helper.h:109
-
hwloc_get_child_covering_cpuset
static hwloc_obj_t hwloc_get_child_covering_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_t parent)
Get the child covering at least CPU set set.
Definition: helper.h:275
-
hwloc_get_obj_covering_cpuset
static hwloc_obj_t hwloc_get_obj_covering_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t set)
Get the lowest object covering at least CPU set set.
Definition: helper.h:297
-
hwloc_get_next_obj_covering_cpuset_by_type
static hwloc_obj_t hwloc_get_next_obj_covering_cpuset_by_type(hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_type_t type, hwloc_obj_t prev)
Iterate through same-type objects covering at least CPU set set.
Definition: helper.h:348
-
hwloc_get_next_obj_covering_cpuset_by_depth
static hwloc_obj_t hwloc_get_next_obj_covering_cpuset_by_depth(hwloc_topology_t topology, hwloc_const_cpuset_t set, int depth, hwloc_obj_t prev)
Iterate through same-depth objects covering at least CPU set set.
Definition: helper.h:321
-
hwloc_get_next_child
static hwloc_obj_t hwloc_get_next_child(hwloc_topology_t topology, hwloc_obj_t parent, hwloc_obj_t prev)
Return the next child.
Definition: helper.h:456
-
hwloc_obj_is_in_subtree
static int hwloc_obj_is_in_subtree(hwloc_topology_t topology, hwloc_obj_t obj, hwloc_obj_t subtree_root)
Returns true if obj is inside the subtree beginning with ancestor object subtree_root.
Definition: helper.h:440
-
hwloc_get_ancestor_obj_by_type
static hwloc_obj_t hwloc_get_ancestor_obj_by_type(hwloc_topology_t topology, hwloc_obj_type_t type, hwloc_obj_t obj)
Returns the ancestor object of obj with type type.
Definition: helper.h:400
-
hwloc_get_ancestor_obj_by_depth
static hwloc_obj_t hwloc_get_ancestor_obj_by_depth(hwloc_topology_t topology, int depth, hwloc_obj_t obj)
Returns the ancestor object of obj at depth depth.
Definition: helper.h:380
-
hwloc_get_common_ancestor_obj
static hwloc_obj_t hwloc_get_common_ancestor_obj(hwloc_topology_t topology, hwloc_obj_t obj1, hwloc_obj_t obj2)
Returns the common parent object to objects obj1 and obj2.
Definition: helper.h:412
-
hwloc_obj_type_is_memory
int hwloc_obj_type_is_memory(hwloc_obj_type_t type)
Check whether an object type is Memory.
-
hwloc_obj_type_is_cache
int hwloc_obj_type_is_cache(hwloc_obj_type_t type)
Check whether an object type is a CPU Cache (Data, Unified or Instruction).
-
hwloc_obj_type_is_dcache
int hwloc_obj_type_is_dcache(hwloc_obj_type_t type)
Check whether an object type is a CPU Data or Unified Cache.
-
hwloc_obj_type_is_normal
int hwloc_obj_type_is_normal(hwloc_obj_type_t type)
Check whether an object type is Normal.
-
hwloc_obj_type_is_icache
int hwloc_obj_type_is_icache(hwloc_obj_type_t type)
Check whether an object type is a CPU Instruction Cache,.
-
hwloc_obj_type_is_io
int hwloc_obj_type_is_io(hwloc_obj_type_t type)
Check whether an object type is I/O.
-
hwloc_get_shared_cache_covering_obj
static hwloc_obj_t hwloc_get_shared_cache_covering_obj(hwloc_topology_t topology, hwloc_obj_t obj)
Get the first data (or unified) cache shared between an object and somebody else.
Definition: helper.h:648
-
hwloc_get_cache_covering_cpuset
static hwloc_obj_t hwloc_get_cache_covering_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t set)
Get the first data (or unified) cache covering a cpuset set.
Definition: helper.h:630
-
hwloc_get_cache_type_depth
static int hwloc_get_cache_type_depth(hwloc_topology_t topology, unsigned cachelevel, hwloc_obj_cache_type_t cachetype)
Find the depth of cache objects matching cache level and type.
Definition: helper.h:594
-
hwloc_bitmap_singlify_per_core
int hwloc_bitmap_singlify_per_core(hwloc_topology_t topology, hwloc_bitmap_t cpuset, unsigned which)
Remove simultaneous multithreading PUs from a CPU set.
-
hwloc_get_closest_objs
unsigned hwloc_get_closest_objs(hwloc_topology_t topology, hwloc_obj_t src, hwloc_obj_t *restrict objs, unsigned max)
Do a depth-first traversal of the topology to find and sort.
-
hwloc_get_pu_obj_by_os_index
static hwloc_obj_t hwloc_get_pu_obj_by_os_index(hwloc_topology_t topology, unsigned os_index)
Returns the object of type HWLOC_OBJ_PU with os_index.
Definition: helper.h:705
-
hwloc_get_obj_below_by_type
static hwloc_obj_t hwloc_get_obj_below_by_type(hwloc_topology_t topology, hwloc_obj_type_t type1, unsigned idx1, hwloc_obj_type_t type2, unsigned idx2)
Find an object below another object, both specified by types and indexes.
Definition: helper.h:766
-
hwloc_get_obj_with_same_locality
hwloc_obj_t hwloc_get_obj_with_same_locality(hwloc_topology_t topology, hwloc_obj_t src, hwloc_obj_type_t type, const char *subtype, const char *nameprefix, unsigned long flags)
Return an object of a different type with same locality.
-
hwloc_get_numanode_obj_by_os_index
static hwloc_obj_t hwloc_get_numanode_obj_by_os_index(hwloc_topology_t topology, unsigned os_index)
Returns the object of type HWLOC_OBJ_NUMANODE with os_index.
Definition: helper.h:726
-
hwloc_get_obj_below_array_by_type
static hwloc_obj_t hwloc_get_obj_below_array_by_type(hwloc_topology_t topology, int nr, hwloc_obj_type_t *typev, unsigned *idxv)
Find an object below a chain of objects specified by types and indexes.
Definition: helper.h:798
-
hwloc_distrib
static int hwloc_distrib(hwloc_topology_t topology, hwloc_obj_t *roots, unsigned n_roots, hwloc_cpuset_t *set, unsigned n, int until, unsigned long flags)
Distribute n items over the topology under roots.
Definition: helper.h:891
-
hwloc_distrib_flags_e
hwloc_distrib_flags_e
Flags to be given to hwloc_distrib().
Definition: helper.h:863
-
HWLOC_DISTRIB_FLAG_REVERSE
@ HWLOC_DISTRIB_FLAG_REVERSE
Distrib in reverse order, starting from the last objects.
Definition: helper.h:867
-
hwloc_topology_get_allowed_nodeset
hwloc_const_nodeset_t hwloc_topology_get_allowed_nodeset(hwloc_topology_t topology)
Get allowed node set.
-
hwloc_topology_get_topology_nodeset
hwloc_const_nodeset_t hwloc_topology_get_topology_nodeset(hwloc_topology_t topology)
Get topology node set.
-
hwloc_topology_get_allowed_cpuset
hwloc_const_cpuset_t hwloc_topology_get_allowed_cpuset(hwloc_topology_t topology)
Get allowed CPU set.
-
hwloc_topology_get_complete_nodeset
hwloc_const_nodeset_t hwloc_topology_get_complete_nodeset(hwloc_topology_t topology)
Get complete node set.
-
hwloc_topology_get_topology_cpuset
hwloc_const_cpuset_t hwloc_topology_get_topology_cpuset(hwloc_topology_t topology)
Get topology CPU set.
-
hwloc_topology_get_complete_cpuset
hwloc_const_cpuset_t hwloc_topology_get_complete_cpuset(hwloc_topology_t topology)
Get complete CPU set.
-
hwloc_cpuset_to_nodeset
static int hwloc_cpuset_to_nodeset(hwloc_topology_t topology, hwloc_const_cpuset_t _cpuset, hwloc_nodeset_t nodeset)
Convert a CPU set into a NUMA node set.
Definition: helper.h:1071
-
hwloc_cpuset_from_nodeset
static int hwloc_cpuset_from_nodeset(hwloc_topology_t topology, hwloc_cpuset_t _cpuset, hwloc_const_nodeset_t nodeset)
Convert a NUMA node set into a CPU set.
Definition: helper.h:1095
-
hwloc_bridge_covers_pcibus
static int hwloc_bridge_covers_pcibus(hwloc_obj_t bridge, unsigned domain, unsigned bus)
Definition: helper.h:1209
-
hwloc_get_pcidev_by_busidstring
static hwloc_obj_t hwloc_get_pcidev_by_busidstring(hwloc_topology_t topology, const char *busid)
Find the PCI device object matching the PCI bus id given as a string xxxx:yy:zz.t or yy:zz....
Definition: helper.h:1172
-
hwloc_get_next_pcidev
static hwloc_obj_t hwloc_get_next_pcidev(hwloc_topology_t topology, hwloc_obj_t prev)
Get the next PCI device in the system.
Definition: helper.h:1145
-
hwloc_get_next_osdev
static hwloc_obj_t hwloc_get_next_osdev(hwloc_topology_t topology, hwloc_obj_t prev)
Get the next OS device in the system.
Definition: helper.h:1191
-
hwloc_get_next_bridge
static hwloc_obj_t hwloc_get_next_bridge(hwloc_topology_t topology, hwloc_obj_t prev)
Get the next bridge in the system.
Definition: helper.h:1201
-
hwloc_get_pcidev_by_busid
static hwloc_obj_t hwloc_get_pcidev_by_busid(hwloc_topology_t topology, unsigned domain, unsigned bus, unsigned dev, unsigned func)
Find the PCI device object matching the PCI bus id given domain, bus device and function PCI bus id.
Definition: helper.h:1154
-
hwloc_get_non_io_ancestor_obj
static hwloc_obj_t hwloc_get_non_io_ancestor_obj(hwloc_topology_t topology, hwloc_obj_t ioobj)
Get the first non-I/O ancestor object.
Definition: helper.h:1130
-
hwloc_bitmap_weight
int hwloc_bitmap_weight(hwloc_const_bitmap_t bitmap)
Compute the "weight" of bitmap bitmap (i.e., number of indexes that are in the bitmap).
-
hwloc_bitmap_isincluded
int hwloc_bitmap_isincluded(hwloc_const_bitmap_t sub_bitmap, hwloc_const_bitmap_t super_bitmap)
Test whether bitmap sub_bitmap is part of bitmap super_bitmap.
-
hwloc_bitmap_set
int hwloc_bitmap_set(hwloc_bitmap_t bitmap, unsigned id)
Add index id in bitmap bitmap.
-
hwloc_bitmap_isset
int hwloc_bitmap_isset(hwloc_const_bitmap_t bitmap, unsigned id)
Test whether index id is part of bitmap bitmap.
-
hwloc_bitmap_or
int hwloc_bitmap_or(hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
Or bitmaps bitmap1 and bitmap2 and store the result in bitmap res.
-
hwloc_bitmap_isequal
int hwloc_bitmap_isequal(hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
Test whether bitmap bitmap1 is equal to bitmap bitmap2.
-
hwloc_bitmap_iszero
int hwloc_bitmap_iszero(hwloc_const_bitmap_t bitmap)
Test whether bitmap bitmap is empty.
-
hwloc_bitmap_t
struct hwloc_bitmap_s * hwloc_bitmap_t
Set of bits represented as an opaque pointer to an internal bitmap.
Definition: bitmap.h:68
-
hwloc_bitmap_zero
void hwloc_bitmap_zero(hwloc_bitmap_t bitmap)
Empty the bitmap bitmap.
-
hwloc_bitmap_dup
hwloc_bitmap_t hwloc_bitmap_dup(hwloc_const_bitmap_t bitmap)
Duplicate bitmap bitmap by allocating a new bitmap and copying bitmap contents.
-
hwloc_bitmap_intersects
int hwloc_bitmap_intersects(hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
Test whether bitmaps bitmap1 and bitmap2 intersects.
-
hwloc_obj
Structure of a topology object.
Definition: hwloc.h:396
-
hwloc_obj::children
struct hwloc_obj ** children
Normal children, children[0 .. arity -1].
Definition: hwloc.h:456
-
hwloc_obj::nodeset
hwloc_nodeset_t nodeset
NUMA nodes covered by this object or containing this object.
Definition: hwloc.h:540
-
hwloc_obj::depth
int depth
Vertical index in the hierarchy.
Definition: hwloc.h:419
-
hwloc_obj::misc_first_child
struct hwloc_obj * misc_first_child
First Misc child. Misc objects are listed here (misc_arity and misc_first_child) instead of in the no...
Definition: hwloc.h:505
-
hwloc_obj::subtype
char * subtype
Subtype string to better describe the type field.
Definition: hwloc.h:399
-
hwloc_obj::os_index
unsigned os_index
OS-provided physical index number. It is not guaranteed unique across the entire machine,...
Definition: hwloc.h:401
-
hwloc_obj::cpuset
hwloc_cpuset_t cpuset
CPUs covered by this object.
Definition: hwloc.h:512
-
hwloc_obj::next_sibling
struct hwloc_obj * next_sibling
Next object below the same parent (inside the same list of children).
Definition: hwloc.h:448
-
hwloc_obj::next_cousin
struct hwloc_obj * next_cousin
Next object of same type and depth.
Definition: hwloc.h:442
-
hwloc_obj::io_first_child
struct hwloc_obj * io_first_child
First I/O child. Bridges, PCI and OS devices are listed here (io_arity and io_first_child) instead of...
Definition: hwloc.h:493
-
hwloc_obj::arity
unsigned arity
Number of normal children. Memory, Misc and I/O children are not listed here but rather in their dedi...
Definition: hwloc.h:452
-
hwloc_obj::memory_first_child
struct hwloc_obj * memory_first_child
First Memory child. NUMA nodes and Memory-side caches are listed here (memory_arity and memory_first_...
Definition: hwloc.h:475
-
hwloc_obj::prev_cousin
struct hwloc_obj * prev_cousin
Previous object of same type and depth.
Definition: hwloc.h:443
-
hwloc_obj::type
hwloc_obj_type_t type
Type of object.
Definition: hwloc.h:398
-
hwloc_obj::attr
union hwloc_obj_attr_u * attr
Object type-specific Attributes, may be NULL if no attribute value was found.
Definition: hwloc.h:415
-
hwloc_obj::parent
struct hwloc_obj * parent
Parent, NULL if root (Machine object)
Definition: hwloc.h:446
-
hwloc_obj::first_child
struct hwloc_obj * first_child
First normal child.
Definition: hwloc.h:457
-
hwloc_obj_attr_u::pcidev
struct hwloc_obj_attr_u::hwloc_pcidev_attr_s pcidev
-
hwloc_obj_attr_u::bridge
struct hwloc_obj_attr_u::hwloc_bridge_attr_s bridge
-
hwloc_obj_attr_u::cache
struct hwloc_obj_attr_u::hwloc_cache_attr_s cache
-
hwloc_obj_attr_u::hwloc_cache_attr_s::depth
unsigned depth
Depth of cache (e.g., L1, L2, ...etc.)
Definition: hwloc.h:618
-
hwloc_obj_attr_u::hwloc_cache_attr_s::type
hwloc_obj_cache_type_t type
Cache type.
Definition: hwloc.h:622
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::dev
unsigned char dev
Definition: hwloc.h:639
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::func
unsigned char func
Definition: hwloc.h:639
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::domain
unsigned short domain
Definition: hwloc.h:635
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::bus
unsigned char bus
Definition: hwloc.h:639
-
hwloc_obj_attr_u::hwloc_bridge_attr_s::downstream
union hwloc_obj_attr_u::hwloc_bridge_attr_s::@1 downstream
-
hwloc_obj_attr_u::hwloc_bridge_attr_s::pci
struct hwloc_pcidev_attr_s pci
Definition: hwloc.h:648
-
hwloc_obj_attr_u::hwloc_bridge_attr_s::downstream_type
hwloc_obj_bridge_type_t downstream_type
Definition: hwloc.h:661
-
- - - - - - - - -
-
-
bitmap.h
-
-
-
1 /*
-
2  * Copyright © 2009 CNRS
-
3  * Copyright © 2009-2022 Inria. All rights reserved.
-
4  * Copyright © 2009-2012 Université Bordeaux
-
5  * Copyright © 2009-2011 Cisco Systems, Inc. All rights reserved.
-
6  * See COPYING in top-level directory.
-
7  */
-
8 
-
13 #ifndef HWLOC_BITMAP_H
-
14 #define HWLOC_BITMAP_H
-
15 
-
16 #include "hwloc/autogen/config.h"
-
17 
-
18 #include <assert.h>
-
19 
-
20 
-
21 #ifdef __cplusplus
-
22 extern "C" {
-
23 #endif
-
24 
-
25 
-
68 typedef struct hwloc_bitmap_s * hwloc_bitmap_t;
-
70 typedef const struct hwloc_bitmap_s * hwloc_const_bitmap_t;
-
71 
-
72 
-
73 /*
-
74  * Bitmap allocation, freeing and copying.
-
75  */
-
76 
-
84 HWLOC_DECLSPEC hwloc_bitmap_t hwloc_bitmap_alloc(void) __hwloc_attribute_malloc;
-
85 
-
87 HWLOC_DECLSPEC hwloc_bitmap_t hwloc_bitmap_alloc_full(void) __hwloc_attribute_malloc;
-
88 
-
93 HWLOC_DECLSPEC void hwloc_bitmap_free(hwloc_bitmap_t bitmap);
-
94 
-
99 HWLOC_DECLSPEC hwloc_bitmap_t hwloc_bitmap_dup(hwloc_const_bitmap_t bitmap) __hwloc_attribute_malloc;
-
100 
-
102 HWLOC_DECLSPEC int hwloc_bitmap_copy(hwloc_bitmap_t dst, hwloc_const_bitmap_t src);
-
103 
-
104 
-
105 /*
-
106  * Bitmap/String Conversion
-
107  */
-
108 
-
118 HWLOC_DECLSPEC int hwloc_bitmap_snprintf(char * __hwloc_restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap);
-
119 
-
124 HWLOC_DECLSPEC int hwloc_bitmap_asprintf(char ** strp, hwloc_const_bitmap_t bitmap);
-
125 
-
128 HWLOC_DECLSPEC int hwloc_bitmap_sscanf(hwloc_bitmap_t bitmap, const char * __hwloc_restrict string);
-
129 
-
143 HWLOC_DECLSPEC int hwloc_bitmap_list_snprintf(char * __hwloc_restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap);
-
144 
-
149 HWLOC_DECLSPEC int hwloc_bitmap_list_asprintf(char ** strp, hwloc_const_bitmap_t bitmap);
-
150 
-
153 HWLOC_DECLSPEC int hwloc_bitmap_list_sscanf(hwloc_bitmap_t bitmap, const char * __hwloc_restrict string);
-
154 
-
167 HWLOC_DECLSPEC int hwloc_bitmap_taskset_snprintf(char * __hwloc_restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap);
-
168 
-
173 HWLOC_DECLSPEC int hwloc_bitmap_taskset_asprintf(char ** strp, hwloc_const_bitmap_t bitmap);
-
174 
-
177 HWLOC_DECLSPEC int hwloc_bitmap_taskset_sscanf(hwloc_bitmap_t bitmap, const char * __hwloc_restrict string);
-
178 
-
179 
-
180 /*
-
181  * Building bitmaps.
-
182  */
-
183 
-
185 HWLOC_DECLSPEC void hwloc_bitmap_zero(hwloc_bitmap_t bitmap);
-
186 
-
188 HWLOC_DECLSPEC void hwloc_bitmap_fill(hwloc_bitmap_t bitmap);
-
189 
-
191 HWLOC_DECLSPEC int hwloc_bitmap_only(hwloc_bitmap_t bitmap, unsigned id);
-
192 
-
194 HWLOC_DECLSPEC int hwloc_bitmap_allbut(hwloc_bitmap_t bitmap, unsigned id);
-
195 
-
197 HWLOC_DECLSPEC int hwloc_bitmap_from_ulong(hwloc_bitmap_t bitmap, unsigned long mask);
-
198 
-
200 HWLOC_DECLSPEC int hwloc_bitmap_from_ith_ulong(hwloc_bitmap_t bitmap, unsigned i, unsigned long mask);
-
201 
-
203 HWLOC_DECLSPEC int hwloc_bitmap_from_ulongs(hwloc_bitmap_t bitmap, unsigned nr, const unsigned long *masks);
-
204 
-
205 
-
206 /*
-
207  * Modifying bitmaps.
-
208  */
-
209 
-
211 HWLOC_DECLSPEC int hwloc_bitmap_set(hwloc_bitmap_t bitmap, unsigned id);
-
212 
-
217 HWLOC_DECLSPEC int hwloc_bitmap_set_range(hwloc_bitmap_t bitmap, unsigned begin, int end);
-
218 
-
220 HWLOC_DECLSPEC int hwloc_bitmap_set_ith_ulong(hwloc_bitmap_t bitmap, unsigned i, unsigned long mask);
-
221 
-
223 HWLOC_DECLSPEC int hwloc_bitmap_clr(hwloc_bitmap_t bitmap, unsigned id);
-
224 
-
229 HWLOC_DECLSPEC int hwloc_bitmap_clr_range(hwloc_bitmap_t bitmap, unsigned begin, int end);
-
230 
-
250 HWLOC_DECLSPEC int hwloc_bitmap_singlify(hwloc_bitmap_t bitmap);
-
251 
-
252 
-
253 /*
-
254  * Consulting bitmaps.
-
255  */
-
256 
-
258 HWLOC_DECLSPEC unsigned long hwloc_bitmap_to_ulong(hwloc_const_bitmap_t bitmap) __hwloc_attribute_pure;
-
259 
-
261 HWLOC_DECLSPEC unsigned long hwloc_bitmap_to_ith_ulong(hwloc_const_bitmap_t bitmap, unsigned i) __hwloc_attribute_pure;
-
262 
-
269 HWLOC_DECLSPEC int hwloc_bitmap_to_ulongs(hwloc_const_bitmap_t bitmap, unsigned nr, unsigned long *masks);
-
270 
-
284 HWLOC_DECLSPEC int hwloc_bitmap_nr_ulongs(hwloc_const_bitmap_t bitmap) __hwloc_attribute_pure;
-
285 
-
290 HWLOC_DECLSPEC int hwloc_bitmap_isset(hwloc_const_bitmap_t bitmap, unsigned id) __hwloc_attribute_pure;
-
291 
-
296 HWLOC_DECLSPEC int hwloc_bitmap_iszero(hwloc_const_bitmap_t bitmap) __hwloc_attribute_pure;
-
297 
-
304 HWLOC_DECLSPEC int hwloc_bitmap_isfull(hwloc_const_bitmap_t bitmap) __hwloc_attribute_pure;
-
305 
-
310 HWLOC_DECLSPEC int hwloc_bitmap_first(hwloc_const_bitmap_t bitmap) __hwloc_attribute_pure;
-
311 
-
318 HWLOC_DECLSPEC int hwloc_bitmap_next(hwloc_const_bitmap_t bitmap, int prev) __hwloc_attribute_pure;
-
319 
-
324 HWLOC_DECLSPEC int hwloc_bitmap_last(hwloc_const_bitmap_t bitmap) __hwloc_attribute_pure;
-
325 
-
333 HWLOC_DECLSPEC int hwloc_bitmap_weight(hwloc_const_bitmap_t bitmap) __hwloc_attribute_pure;
-
334 
-
339 HWLOC_DECLSPEC int hwloc_bitmap_first_unset(hwloc_const_bitmap_t bitmap) __hwloc_attribute_pure;
-
340 
-
347 HWLOC_DECLSPEC int hwloc_bitmap_next_unset(hwloc_const_bitmap_t bitmap, int prev) __hwloc_attribute_pure;
-
348 
-
353 HWLOC_DECLSPEC int hwloc_bitmap_last_unset(hwloc_const_bitmap_t bitmap) __hwloc_attribute_pure;
-
354 
-
370 #define hwloc_bitmap_foreach_begin(id, bitmap) \
-
371 do { \
-
372  assert(hwloc_bitmap_weight(bitmap) != -1); \
-
373  for (id = hwloc_bitmap_first(bitmap); \
-
374  (unsigned) id != (unsigned) -1; \
-
375  id = hwloc_bitmap_next(bitmap, id)) {
-
376 
-
384 #define hwloc_bitmap_foreach_end() \
-
385  } \
-
386 } while (0)
-
387 
-
388 
-
389 /*
-
390  * Combining bitmaps.
-
391  */
-
392 
-
397 HWLOC_DECLSPEC int hwloc_bitmap_or (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2);
-
398 
-
403 HWLOC_DECLSPEC int hwloc_bitmap_and (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2);
-
404 
-
409 HWLOC_DECLSPEC int hwloc_bitmap_andnot (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2);
-
410 
-
415 HWLOC_DECLSPEC int hwloc_bitmap_xor (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2);
-
416 
-
421 HWLOC_DECLSPEC int hwloc_bitmap_not (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap);
-
422 
-
423 
-
424 /*
-
425  * Comparing bitmaps.
-
426  */
-
427 
-
432 HWLOC_DECLSPEC int hwloc_bitmap_intersects (hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2) __hwloc_attribute_pure;
-
433 
-
440 HWLOC_DECLSPEC int hwloc_bitmap_isincluded (hwloc_const_bitmap_t sub_bitmap, hwloc_const_bitmap_t super_bitmap) __hwloc_attribute_pure;
-
441 
-
446 HWLOC_DECLSPEC int hwloc_bitmap_isequal (hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2) __hwloc_attribute_pure;
-
447 
-
465 HWLOC_DECLSPEC int hwloc_bitmap_compare_first(hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2) __hwloc_attribute_pure;
-
466 
-
484 HWLOC_DECLSPEC int hwloc_bitmap_compare(hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2) __hwloc_attribute_pure;
-
485 
-
489 #ifdef __cplusplus
-
490 } /* extern "C" */
-
491 #endif
-
492 
-
493 
-
494 #endif /* HWLOC_BITMAP_H */
-
hwloc_bitmap_weight
int hwloc_bitmap_weight(hwloc_const_bitmap_t bitmap)
Compute the "weight" of bitmap bitmap (i.e., number of indexes that are in the bitmap).
-
hwloc_bitmap_alloc_full
hwloc_bitmap_t hwloc_bitmap_alloc_full(void)
Allocate a new full bitmap.
-
hwloc_bitmap_isincluded
int hwloc_bitmap_isincluded(hwloc_const_bitmap_t sub_bitmap, hwloc_const_bitmap_t super_bitmap)
Test whether bitmap sub_bitmap is part of bitmap super_bitmap.
-
hwloc_bitmap_set
int hwloc_bitmap_set(hwloc_bitmap_t bitmap, unsigned id)
Add index id in bitmap bitmap.
-
hwloc_bitmap_sscanf
int hwloc_bitmap_sscanf(hwloc_bitmap_t bitmap, const char *restrict string)
Parse a bitmap string and stores it in bitmap bitmap.
-
hwloc_bitmap_allbut
int hwloc_bitmap_allbut(hwloc_bitmap_t bitmap, unsigned id)
Fill the bitmap and clear the index id.
-
hwloc_bitmap_fill
void hwloc_bitmap_fill(hwloc_bitmap_t bitmap)
Fill bitmap bitmap with all possible indexes (even if those objects don't exist or are otherwise unav...
-
hwloc_bitmap_asprintf
int hwloc_bitmap_asprintf(char **strp, hwloc_const_bitmap_t bitmap)
Stringify a bitmap into a newly allocated string.
-
hwloc_bitmap_only
int hwloc_bitmap_only(hwloc_bitmap_t bitmap, unsigned id)
Empty the bitmap bitmap and add bit id.
-
hwloc_bitmap_isset
int hwloc_bitmap_isset(hwloc_const_bitmap_t bitmap, unsigned id)
Test whether index id is part of bitmap bitmap.
-
hwloc_bitmap_or
int hwloc_bitmap_or(hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
Or bitmaps bitmap1 and bitmap2 and store the result in bitmap res.
-
hwloc_bitmap_compare
int hwloc_bitmap_compare(hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
Compare bitmaps bitmap1 and bitmap2 in lexicographic order.
-
hwloc_bitmap_free
void hwloc_bitmap_free(hwloc_bitmap_t bitmap)
Free bitmap bitmap.
-
hwloc_bitmap_xor
int hwloc_bitmap_xor(hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
Xor bitmaps bitmap1 and bitmap2 and store the result in bitmap res.
-
hwloc_bitmap_isequal
int hwloc_bitmap_isequal(hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
Test whether bitmap bitmap1 is equal to bitmap bitmap2.
-
hwloc_bitmap_taskset_asprintf
int hwloc_bitmap_taskset_asprintf(char **strp, hwloc_const_bitmap_t bitmap)
Stringify a bitmap into a newly allocated taskset-specific string.
-
hwloc_bitmap_list_asprintf
int hwloc_bitmap_list_asprintf(char **strp, hwloc_const_bitmap_t bitmap)
Stringify a bitmap into a newly allocated list string.
-
hwloc_bitmap_list_snprintf
int hwloc_bitmap_list_snprintf(char *restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap)
Stringify a bitmap in the list format.
-
hwloc_bitmap_last
int hwloc_bitmap_last(hwloc_const_bitmap_t bitmap)
Compute the last index (most significant bit) in bitmap bitmap.
-
hwloc_bitmap_set_ith_ulong
int hwloc_bitmap_set_ith_ulong(hwloc_bitmap_t bitmap, unsigned i, unsigned long mask)
Replace i -th subset of bitmap bitmap with unsigned long mask.
-
hwloc_bitmap_first
int hwloc_bitmap_first(hwloc_const_bitmap_t bitmap)
Compute the first index (least significant bit) in bitmap bitmap.
-
hwloc_bitmap_last_unset
int hwloc_bitmap_last_unset(hwloc_const_bitmap_t bitmap)
Compute the last unset index (most significant bit) in bitmap bitmap.
-
hwloc_bitmap_from_ith_ulong
int hwloc_bitmap_from_ith_ulong(hwloc_bitmap_t bitmap, unsigned i, unsigned long mask)
Setup bitmap bitmap from unsigned long mask used as i -th subset.
-
hwloc_bitmap_taskset_sscanf
int hwloc_bitmap_taskset_sscanf(hwloc_bitmap_t bitmap, const char *restrict string)
Parse a taskset-specific bitmap string and stores it in bitmap bitmap.
-
hwloc_bitmap_iszero
int hwloc_bitmap_iszero(hwloc_const_bitmap_t bitmap)
Test whether bitmap bitmap is empty.
-
hwloc_bitmap_taskset_snprintf
int hwloc_bitmap_taskset_snprintf(char *restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap)
Stringify a bitmap in the taskset-specific format.
-
hwloc_bitmap_isfull
int hwloc_bitmap_isfull(hwloc_const_bitmap_t bitmap)
Test whether bitmap bitmap is completely full.
-
hwloc_bitmap_and
int hwloc_bitmap_and(hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
And bitmaps bitmap1 and bitmap2 and store the result in bitmap res.
-
hwloc_bitmap_copy
int hwloc_bitmap_copy(hwloc_bitmap_t dst, hwloc_const_bitmap_t src)
Copy the contents of bitmap src into the already allocated bitmap dst.
-
hwloc_bitmap_andnot
int hwloc_bitmap_andnot(hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
And bitmap bitmap1 and the negation of bitmap2 and store the result in bitmap res.
-
hwloc_bitmap_clr_range
int hwloc_bitmap_clr_range(hwloc_bitmap_t bitmap, unsigned begin, int end)
Remove indexes from begin to end in bitmap bitmap.
-
hwloc_bitmap_not
int hwloc_bitmap_not(hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap)
Negate bitmap bitmap and store the result in bitmap res.
-
hwloc_bitmap_snprintf
int hwloc_bitmap_snprintf(char *restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap)
Stringify a bitmap.
-
hwloc_bitmap_next_unset
int hwloc_bitmap_next_unset(hwloc_const_bitmap_t bitmap, int prev)
Compute the next unset index in bitmap bitmap which is after index prev.
-
hwloc_bitmap_set_range
int hwloc_bitmap_set_range(hwloc_bitmap_t bitmap, unsigned begin, int end)
Add indexes from begin to end in bitmap bitmap.
-
hwloc_bitmap_compare_first
int hwloc_bitmap_compare_first(hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
Compare bitmaps bitmap1 and bitmap2 using their lowest index.
-
hwloc_bitmap_t
struct hwloc_bitmap_s * hwloc_bitmap_t
Set of bits represented as an opaque pointer to an internal bitmap.
Definition: bitmap.h:68
-
hwloc_bitmap_singlify
int hwloc_bitmap_singlify(hwloc_bitmap_t bitmap)
Keep a single index among those set in bitmap bitmap.
-
hwloc_bitmap_zero
void hwloc_bitmap_zero(hwloc_bitmap_t bitmap)
Empty the bitmap bitmap.
-
hwloc_bitmap_next
int hwloc_bitmap_next(hwloc_const_bitmap_t bitmap, int prev)
Compute the next index in bitmap bitmap which is after index prev.
-
hwloc_bitmap_to_ulong
unsigned long hwloc_bitmap_to_ulong(hwloc_const_bitmap_t bitmap)
Convert the beginning part of bitmap bitmap into unsigned long mask.
-
hwloc_bitmap_from_ulongs
int hwloc_bitmap_from_ulongs(hwloc_bitmap_t bitmap, unsigned nr, const unsigned long *masks)
Setup bitmap bitmap from unsigned longs masks used as first nr subsets.
-
hwloc_bitmap_nr_ulongs
int hwloc_bitmap_nr_ulongs(hwloc_const_bitmap_t bitmap)
Return the number of unsigned longs required for storing bitmap bitmap entirely.
-
hwloc_bitmap_to_ith_ulong
unsigned long hwloc_bitmap_to_ith_ulong(hwloc_const_bitmap_t bitmap, unsigned i)
Convert the i -th subset of bitmap bitmap into unsigned long mask.
-
hwloc_bitmap_to_ulongs
int hwloc_bitmap_to_ulongs(hwloc_const_bitmap_t bitmap, unsigned nr, unsigned long *masks)
Convert the first nr subsets of bitmap bitmap into the array of nr unsigned long masks.
-
hwloc_bitmap_from_ulong
int hwloc_bitmap_from_ulong(hwloc_bitmap_t bitmap, unsigned long mask)
Setup bitmap bitmap from unsigned long mask.
-
hwloc_bitmap_alloc
hwloc_bitmap_t hwloc_bitmap_alloc(void)
Allocate a new empty bitmap.
-
hwloc_bitmap_first_unset
int hwloc_bitmap_first_unset(hwloc_const_bitmap_t bitmap)
Compute the first unset index (least significant bit) in bitmap bitmap.
-
hwloc_bitmap_dup
hwloc_bitmap_t hwloc_bitmap_dup(hwloc_const_bitmap_t bitmap)
Duplicate bitmap bitmap by allocating a new bitmap and copying bitmap contents.
-
hwloc_const_bitmap_t
const struct hwloc_bitmap_s * hwloc_const_bitmap_t
a non-modifiable hwloc_bitmap_t
Definition: bitmap.h:70
-
hwloc_bitmap_intersects
int hwloc_bitmap_intersects(hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
Test whether bitmaps bitmap1 and bitmap2 intersects.
-
hwloc_bitmap_clr
int hwloc_bitmap_clr(hwloc_bitmap_t bitmap, unsigned id)
Remove index id from bitmap bitmap.
-
hwloc_bitmap_list_sscanf
int hwloc_bitmap_list_sscanf(hwloc_bitmap_t bitmap, const char *restrict string)
Parse a list string and stores it in bitmap bitmap.
-
- - - - - - - - -
-
-
export.h
-
-
-
1 /*
-
2  * Copyright © 2009-2018 Inria. All rights reserved.
-
3  * Copyright © 2009-2012 Université Bordeaux
-
4  * Copyright © 2009-2011 Cisco Systems, Inc. All rights reserved.
-
5  * See COPYING in top-level directory.
-
6  */
-
7 
-
12 #ifndef HWLOC_EXPORT_H
-
13 #define HWLOC_EXPORT_H
-
14 
-
15 #ifndef HWLOC_H
-
16 #error Please include the main hwloc.h instead
-
17 #endif
-
18 
-
19 
-
20 #ifdef __cplusplus
-
21 extern "C" {
-
22 #elif 0
-
23 }
-
24 #endif
-
25 
-
26 
-
35 enum hwloc_topology_export_xml_flags_e {
-
40  HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1 = (1UL<<0)
-
41 };
-
42 
-
71 HWLOC_DECLSPEC int hwloc_topology_export_xml(hwloc_topology_t topology, const char *xmlpath, unsigned long flags);
-
72 
-
105 HWLOC_DECLSPEC int hwloc_topology_export_xmlbuffer(hwloc_topology_t topology, char **xmlbuffer, int *buflen, unsigned long flags);
-
106 
-
108 HWLOC_DECLSPEC void hwloc_free_xmlbuffer(hwloc_topology_t topology, char *xmlbuffer);
-
109 
-
128 HWLOC_DECLSPEC void hwloc_topology_set_userdata_export_callback(hwloc_topology_t topology,
-
129  void (*export_cb)(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj));
-
130 
-
156 HWLOC_DECLSPEC int hwloc_export_obj_userdata(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length);
-
157 
-
171 HWLOC_DECLSPEC int hwloc_export_obj_userdata_base64(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length);
-
172 
-
195 HWLOC_DECLSPEC void hwloc_topology_set_userdata_import_callback(hwloc_topology_t topology,
-
196  void (*import_cb)(hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length));
-
197 
-
209 enum hwloc_topology_export_synthetic_flags_e {
-
215  HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_EXTENDED_TYPES = (1UL<<0),
-
216 
-
223  HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_ATTRS = (1UL<<1),
-
224 
-
233  HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_V1 = (1UL<<2),
-
234 
-
243  HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_IGNORE_MEMORY = (1UL<<3)
-
244 };
-
245 
-
267  HWLOC_DECLSPEC int hwloc_topology_export_synthetic(hwloc_topology_t topology, char *buffer, size_t buflen, unsigned long flags);
-
268 
-
273 #ifdef __cplusplus
-
274 } /* extern "C" */
-
275 #endif
-
276 
-
277 
-
278 #endif /* HWLOC_EXPORT_H */
-
hwloc_topology_t
struct hwloc_topology * hwloc_topology_t
Topology context.
Definition: hwloc.h:692
-
hwloc_topology_export_xml_flags_e
hwloc_topology_export_xml_flags_e
Flags for exporting XML topologies.
Definition: export.h:35
-
hwloc_export_obj_userdata_base64
int hwloc_export_obj_userdata_base64(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length)
Encode and export some object userdata to XML.
-
hwloc_free_xmlbuffer
void hwloc_free_xmlbuffer(hwloc_topology_t topology, char *xmlbuffer)
Free a buffer allocated by hwloc_topology_export_xmlbuffer()
-
hwloc_topology_export_xml
int hwloc_topology_export_xml(hwloc_topology_t topology, const char *xmlpath, unsigned long flags)
Export the topology into an XML file.
-
hwloc_topology_set_userdata_import_callback
void hwloc_topology_set_userdata_import_callback(hwloc_topology_t topology, void(*import_cb)(hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length))
Set the application-specific callback for importing userdata.
-
hwloc_topology_set_userdata_export_callback
void hwloc_topology_set_userdata_export_callback(hwloc_topology_t topology, void(*export_cb)(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj))
Set the application-specific callback for exporting object userdata.
-
hwloc_export_obj_userdata
int hwloc_export_obj_userdata(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length)
Export some object userdata to XML.
-
hwloc_topology_export_xmlbuffer
int hwloc_topology_export_xmlbuffer(hwloc_topology_t topology, char **xmlbuffer, int *buflen, unsigned long flags)
Export the topology into a newly-allocated XML memory buffer.
-
HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1
@ HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1
Export XML that is loadable by hwloc v1.x. However, the export may miss some details about the topolo...
Definition: export.h:40
-
hwloc_topology_export_synthetic
int hwloc_topology_export_synthetic(hwloc_topology_t topology, char *buffer, size_t buflen, unsigned long flags)
Export the topology as a synthetic string.
-
hwloc_topology_export_synthetic_flags_e
hwloc_topology_export_synthetic_flags_e
Flags for exporting synthetic topologies.
Definition: export.h:209
-
HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_IGNORE_MEMORY
@ HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_IGNORE_MEMORY
Do not export memory information.
Definition: export.h:243
-
HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_EXTENDED_TYPES
@ HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_EXTENDED_TYPES
Export extended types such as L2dcache as basic types such as Cache.
Definition: export.h:215
-
HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_V1
@ HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_V1
Export the memory hierarchy as expected in hwloc 1.x.
Definition: export.h:233
-
HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_ATTRS
@ HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_ATTRS
Do not export level attributes.
Definition: export.h:223
-
hwloc_obj
Structure of a topology object.
Definition: hwloc.h:396
-
- - - - - - - - -
-
-
distances.h
-
-
-
1 /*
-
2  * Copyright © 2010-2022 Inria. All rights reserved.
-
3  * See COPYING in top-level directory.
-
4  */
-
5 
-
10 #ifndef HWLOC_DISTANCES_H
-
11 #define HWLOC_DISTANCES_H
-
12 
-
13 #ifndef HWLOC_H
-
14 #error Please include the main hwloc.h instead
-
15 #endif
-
16 
-
17 
-
18 #ifdef __cplusplus
-
19 extern "C" {
-
20 #elif 0
-
21 }
-
22 #endif
-
23 
-
24 
-
53 struct hwloc_distances_s {
-
54  unsigned nbobjs;
-
55  hwloc_obj_t *objs;
-
60  unsigned long kind;
-
61  hwloc_uint64_t *values;
-
66 };
-
67 
-
79 enum hwloc_distances_kind_e {
-
83  HWLOC_DISTANCES_KIND_FROM_OS = (1UL<<0),
-
87  HWLOC_DISTANCES_KIND_FROM_USER = (1UL<<1),
-
88 
-
95  HWLOC_DISTANCES_KIND_MEANS_LATENCY = (1UL<<2),
-
102  HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH = (1UL<<3),
-
103 
-
109  HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES = (1UL<<4)
-
110 };
-
111 
-
135 HWLOC_DECLSPEC int
-
136 hwloc_distances_get(hwloc_topology_t topology,
-
137  unsigned *nr, struct hwloc_distances_s **distances,
-
138  unsigned long kind, unsigned long flags);
-
139 
-
144 HWLOC_DECLSPEC int
-
145 hwloc_distances_get_by_depth(hwloc_topology_t topology, int depth,
-
146  unsigned *nr, struct hwloc_distances_s **distances,
-
147  unsigned long kind, unsigned long flags);
-
148 
-
153 HWLOC_DECLSPEC int
-
154 hwloc_distances_get_by_type(hwloc_topology_t topology, hwloc_obj_type_t type,
-
155  unsigned *nr, struct hwloc_distances_s **distances,
-
156  unsigned long kind, unsigned long flags);
-
157 
-
166 HWLOC_DECLSPEC int
-
167 hwloc_distances_get_by_name(hwloc_topology_t topology, const char *name,
-
168  unsigned *nr, struct hwloc_distances_s **distances,
-
169  unsigned long flags);
-
170 
-
176 HWLOC_DECLSPEC const char *
-
177 hwloc_distances_get_name(hwloc_topology_t topology, struct hwloc_distances_s *distances);
-
178 
-
183 HWLOC_DECLSPEC void
-
184 hwloc_distances_release(hwloc_topology_t topology, struct hwloc_distances_s *distances);
-
185 
-
187 enum hwloc_distances_transform_e {
-
201  HWLOC_DISTANCES_TRANSFORM_REMOVE_NULL = 0,
-
202 
-
215  HWLOC_DISTANCES_TRANSFORM_LINKS = 1,
-
216 
-
224  HWLOC_DISTANCES_TRANSFORM_MERGE_SWITCH_PORTS = 2,
-
225 
-
231  HWLOC_DISTANCES_TRANSFORM_TRANSITIVE_CLOSURE = 3
-
232 };
-
233 
-
260 HWLOC_DECLSPEC int hwloc_distances_transform(hwloc_topology_t topology, struct hwloc_distances_s *distances,
-
261  enum hwloc_distances_transform_e transform,
-
262  void *transform_attr,
-
263  unsigned long flags);
-
264 
-
277 static __hwloc_inline int
-
278 hwloc_distances_obj_index(struct hwloc_distances_s *distances, hwloc_obj_t obj)
-
279 {
-
280  unsigned i;
-
281  for(i=0; i<distances->nbobjs; i++)
-
282  if (distances->objs[i] == obj)
-
283  return (int)i;
-
284  return -1;
-
285 }
-
286 
-
294 static __hwloc_inline int
-
295 hwloc_distances_obj_pair_values(struct hwloc_distances_s *distances,
-
296  hwloc_obj_t obj1, hwloc_obj_t obj2,
-
297  hwloc_uint64_t *value1to2, hwloc_uint64_t *value2to1)
-
298 {
-
299  int i1 = hwloc_distances_obj_index(distances, obj1);
-
300  int i2 = hwloc_distances_obj_index(distances, obj2);
-
301  if (i1 < 0 || i2 < 0)
-
302  return -1;
-
303  *value1to2 = distances->values[i1 * distances->nbobjs + i2];
-
304  *value2to1 = distances->values[i2 * distances->nbobjs + i1];
-
305  return 0;
-
306 }
-
307 
-
331 typedef void * hwloc_distances_add_handle_t;
-
332 
-
353 HWLOC_DECLSPEC hwloc_distances_add_handle_t
-
354 hwloc_distances_add_create(hwloc_topology_t topology,
-
355  const char *name, unsigned long kind,
-
356  unsigned long flags);
-
357 
-
380 HWLOC_DECLSPEC int hwloc_distances_add_values(hwloc_topology_t topology,
-
381  hwloc_distances_add_handle_t handle,
-
382  unsigned nbobjs, hwloc_obj_t *objs,
-
383  hwloc_uint64_t *values,
-
384  unsigned long flags);
-
385 
-
387 enum hwloc_distances_add_flag_e {
-
392  HWLOC_DISTANCES_ADD_FLAG_GROUP = (1UL<<0),
-
398  HWLOC_DISTANCES_ADD_FLAG_GROUP_INACCURATE = (1UL<<1)
-
399 };
-
400 
-
417 HWLOC_DECLSPEC int hwloc_distances_add_commit(hwloc_topology_t topology,
-
418  hwloc_distances_add_handle_t handle,
-
419  unsigned long flags);
-
420 
-
437 HWLOC_DECLSPEC int hwloc_distances_remove(hwloc_topology_t topology);
-
438 
-
443 HWLOC_DECLSPEC int hwloc_distances_remove_by_depth(hwloc_topology_t topology, int depth);
-
444 
-
449 static __hwloc_inline int
-
450 hwloc_distances_remove_by_type(hwloc_topology_t topology, hwloc_obj_type_t type)
-
451 {
-
452  int depth = hwloc_get_type_depth(topology, type);
-
453  if (depth == HWLOC_TYPE_DEPTH_UNKNOWN || depth == HWLOC_TYPE_DEPTH_MULTIPLE)
-
454  return 0;
-
455  return hwloc_distances_remove_by_depth(topology, depth);
-
456 }
-
457 
-
462 HWLOC_DECLSPEC int hwloc_distances_release_remove(hwloc_topology_t topology, struct hwloc_distances_s *distances);
-
463 
-
467 #ifdef __cplusplus
-
468 } /* extern "C" */
-
469 #endif
-
470 
-
471 
-
472 #endif /* HWLOC_DISTANCES_H */
-
hwloc_obj_type_t
hwloc_obj_type_t
Type of topology object.
Definition: hwloc.h:176
-
hwloc_topology_t
struct hwloc_topology * hwloc_topology_t
Topology context.
Definition: hwloc.h:692
-
hwloc_get_type_depth
int hwloc_get_type_depth(hwloc_topology_t topology, hwloc_obj_type_t type)
Returns the depth of objects of type type.
-
HWLOC_TYPE_DEPTH_UNKNOWN
@ HWLOC_TYPE_DEPTH_UNKNOWN
No object of given type exists in the topology.
Definition: hwloc.h:822
-
HWLOC_TYPE_DEPTH_MULTIPLE
@ HWLOC_TYPE_DEPTH_MULTIPLE
Objects of given type exist at different depth in the topology (only for Groups).
Definition: hwloc.h:823
-
hwloc_distances_release
void hwloc_distances_release(hwloc_topology_t topology, struct hwloc_distances_s *distances)
Release a distance matrix structure previously returned by hwloc_distances_get().
-
hwloc_distances_transform_e
hwloc_distances_transform_e
Transformations of distances structures.
Definition: distances.h:187
-
hwloc_distances_get_by_depth
int hwloc_distances_get_by_depth(hwloc_topology_t topology, int depth, unsigned *nr, struct hwloc_distances_s **distances, unsigned long kind, unsigned long flags)
Retrieve distance matrices for object at a specific depth in the topology.
-
hwloc_distances_get
int hwloc_distances_get(hwloc_topology_t topology, unsigned *nr, struct hwloc_distances_s **distances, unsigned long kind, unsigned long flags)
Retrieve distance matrices.
-
hwloc_distances_get_by_name
int hwloc_distances_get_by_name(hwloc_topology_t topology, const char *name, unsigned *nr, struct hwloc_distances_s **distances, unsigned long flags)
Retrieve a distance matrix with the given name.
-
hwloc_distances_get_name
const char * hwloc_distances_get_name(hwloc_topology_t topology, struct hwloc_distances_s *distances)
Get a description of what a distances structure contains.
-
hwloc_distances_get_by_type
int hwloc_distances_get_by_type(hwloc_topology_t topology, hwloc_obj_type_t type, unsigned *nr, struct hwloc_distances_s **distances, unsigned long kind, unsigned long flags)
Retrieve distance matrices for object of a specific type.
-
hwloc_distances_kind_e
hwloc_distances_kind_e
Kinds of distance matrices.
Definition: distances.h:79
-
hwloc_distances_transform
int hwloc_distances_transform(hwloc_topology_t topology, struct hwloc_distances_s *distances, enum hwloc_distances_transform_e transform, void *transform_attr, unsigned long flags)
Apply a transformation to a distances structure.
-
HWLOC_DISTANCES_TRANSFORM_TRANSITIVE_CLOSURE
@ HWLOC_DISTANCES_TRANSFORM_TRANSITIVE_CLOSURE
Apply a transitive closure to the matrix to connect objects across switches. This currently only appl...
Definition: distances.h:231
-
HWLOC_DISTANCES_TRANSFORM_MERGE_SWITCH_PORTS
@ HWLOC_DISTANCES_TRANSFORM_MERGE_SWITCH_PORTS
Merge switches with multiple ports into a single object. This currently only applies to NVSwitches wh...
Definition: distances.h:224
-
HWLOC_DISTANCES_TRANSFORM_LINKS
@ HWLOC_DISTANCES_TRANSFORM_LINKS
Replace bandwidth values with a number of links.
Definition: distances.h:215
-
HWLOC_DISTANCES_TRANSFORM_REMOVE_NULL
@ HWLOC_DISTANCES_TRANSFORM_REMOVE_NULL
Remove NULL objects from the distances structure.
Definition: distances.h:201
-
HWLOC_DISTANCES_KIND_FROM_USER
@ HWLOC_DISTANCES_KIND_FROM_USER
These distances were provided by the user.
Definition: distances.h:87
-
HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH
@ HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH
Distance values are similar to bandwidths between objects. Values are higher for closer objects,...
Definition: distances.h:102
-
HWLOC_DISTANCES_KIND_FROM_OS
@ HWLOC_DISTANCES_KIND_FROM_OS
These distances were obtained from the operating system or hardware.
Definition: distances.h:83
-
HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES
@ HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES
This distances structure covers objects of different types. This may apply to the "NVLinkBandwidth" s...
Definition: distances.h:109
-
HWLOC_DISTANCES_KIND_MEANS_LATENCY
@ HWLOC_DISTANCES_KIND_MEANS_LATENCY
Distance values are similar to latencies between objects. Values are smaller for closer objects,...
Definition: distances.h:95
-
hwloc_distances_obj_pair_values
static int hwloc_distances_obj_pair_values(struct hwloc_distances_s *distances, hwloc_obj_t obj1, hwloc_obj_t obj2, hwloc_uint64_t *value1to2, hwloc_uint64_t *value2to1)
Find the values between two objects in a distance matrices.
Definition: distances.h:295
-
hwloc_distances_obj_index
static int hwloc_distances_obj_index(struct hwloc_distances_s *distances, hwloc_obj_t obj)
Find the index of an object in a distances structure.
Definition: distances.h:278
-
hwloc_distances_add_commit
int hwloc_distances_add_commit(hwloc_topology_t topology, hwloc_distances_add_handle_t handle, unsigned long flags)
Commit a new distances structure.
-
hwloc_distances_add_flag_e
hwloc_distances_add_flag_e
Flags for adding a new distances to a topology.
Definition: distances.h:387
-
hwloc_distances_add_handle_t
void * hwloc_distances_add_handle_t
Handle to a new distances structure during its addition to the topology.
Definition: distances.h:331
-
hwloc_distances_add_create
hwloc_distances_add_handle_t hwloc_distances_add_create(hwloc_topology_t topology, const char *name, unsigned long kind, unsigned long flags)
Create a new empty distances structure.
-
hwloc_distances_add_values
int hwloc_distances_add_values(hwloc_topology_t topology, hwloc_distances_add_handle_t handle, unsigned nbobjs, hwloc_obj_t *objs, hwloc_uint64_t *values, unsigned long flags)
Specify the objects and values in a new empty distances structure.
-
HWLOC_DISTANCES_ADD_FLAG_GROUP_INACCURATE
@ HWLOC_DISTANCES_ADD_FLAG_GROUP_INACCURATE
If grouping, consider the distance values as inaccurate and relax the comparisons during the grouping...
Definition: distances.h:398
-
HWLOC_DISTANCES_ADD_FLAG_GROUP
@ HWLOC_DISTANCES_ADD_FLAG_GROUP
Try to group objects based on the newly provided distance information. This is ignored for distances ...
Definition: distances.h:392
-
hwloc_distances_release_remove
int hwloc_distances_release_remove(hwloc_topology_t topology, struct hwloc_distances_s *distances)
Release and remove the given distance matrice from the topology.
-
hwloc_distances_remove_by_type
static int hwloc_distances_remove_by_type(hwloc_topology_t topology, hwloc_obj_type_t type)
Remove distance matrices for objects of a specific type in the topology.
Definition: distances.h:450
-
hwloc_distances_remove_by_depth
int hwloc_distances_remove_by_depth(hwloc_topology_t topology, int depth)
Remove distance matrices for objects at a specific depth in the topology.
-
hwloc_distances_remove
int hwloc_distances_remove(hwloc_topology_t topology)
Remove all distance matrices from a topology.
-
hwloc_obj
Structure of a topology object.
Definition: hwloc.h:396
-
hwloc_distances_s
Matrix of distances between a set of objects.
Definition: distances.h:53
-
hwloc_distances_s::nbobjs
unsigned nbobjs
Number of objects described by the distance matrix.
Definition: distances.h:54
-
hwloc_distances_s::values
hwloc_uint64_t * values
Matrix of distances between objects, stored as a one-dimension array.
Definition: distances.h:61
-
hwloc_distances_s::kind
unsigned long kind
OR'ed set of hwloc_distances_kind_e.
Definition: distances.h:60
-
hwloc_distances_s::objs
hwloc_obj_t * objs
Array of objects described by the distance matrix. These objects are not in any particular order,...
Definition: distances.h:55
-
- - - - - - - - -
-
-
memattrs.h
-
-
-
1 /*
-
2  * Copyright © 2019-2022 Inria. All rights reserved.
-
3  * See COPYING in top-level directory.
-
4  */
-
5 
-
10 #ifndef HWLOC_MEMATTR_H
-
11 #define HWLOC_MEMATTR_H
-
12 
-
13 #include "hwloc.h"
-
14 
-
15 #ifdef __cplusplus
-
16 extern "C" {
-
17 #elif 0
-
18 }
-
19 #endif
-
20 
-
69 enum hwloc_memattr_id_e {
-
79  HWLOC_MEMATTR_ID_CAPACITY = 0,
-
80 
-
94  HWLOC_MEMATTR_ID_LOCALITY = 1,
-
95 
-
109  HWLOC_MEMATTR_ID_BANDWIDTH = 2,
-
110 
-
120  HWLOC_MEMATTR_ID_READ_BANDWIDTH = 4,
-
121 
-
131  HWLOC_MEMATTR_ID_WRITE_BANDWIDTH = 5,
-
132 
-
146  HWLOC_MEMATTR_ID_LATENCY = 3,
-
147 
-
157  HWLOC_MEMATTR_ID_READ_LATENCY = 6,
-
158 
-
168  HWLOC_MEMATTR_ID_WRITE_LATENCY = 7,
-
169 
-
170  /* TODO persistence? */
-
171 
-
172  HWLOC_MEMATTR_ID_MAX
-
173 };
-
174 
-
178 typedef unsigned hwloc_memattr_id_t;
-
179 
-
182 HWLOC_DECLSPEC int
-
183 hwloc_memattr_get_by_name(hwloc_topology_t topology,
-
184  const char *name,
-
185  hwloc_memattr_id_t *id);
-
186 
-
187 
-
189 enum hwloc_location_type_e {
-
191  HWLOC_LOCATION_TYPE_CPUSET = 1,
-
193  HWLOC_LOCATION_TYPE_OBJECT = 0
-
194 };
-
195 
-
197 struct hwloc_location {
-
199  enum hwloc_location_type_e type;
-
201  union hwloc_location_u {
-
203  hwloc_cpuset_t cpuset;
-
205  hwloc_obj_t object;
-
206  } location;
-
207 };
-
208 
-
209 
-
211 enum hwloc_local_numanode_flag_e {
-
217  HWLOC_LOCAL_NUMANODE_FLAG_LARGER_LOCALITY = (1UL<<0),
-
218 
-
224  HWLOC_LOCAL_NUMANODE_FLAG_SMALLER_LOCALITY = (1UL<<1),
-
225 
-
230  HWLOC_LOCAL_NUMANODE_FLAG_ALL = (1UL<<2)
-
231 };
-
232 
-
262 HWLOC_DECLSPEC int
-
263 hwloc_get_local_numanode_objs(hwloc_topology_t topology,
-
264  struct hwloc_location *location,
-
265  unsigned *nr,
-
266  hwloc_obj_t *nodes,
-
267  unsigned long flags);
-
268 
-
269 
-
270 
-
285 HWLOC_DECLSPEC int
-
286 hwloc_memattr_get_value(hwloc_topology_t topology,
-
287  hwloc_memattr_id_t attribute,
-
288  hwloc_obj_t target_node,
-
289  struct hwloc_location *initiator,
-
290  unsigned long flags,
-
291  hwloc_uint64_t *value);
-
292 
-
318 HWLOC_DECLSPEC int
-
319 hwloc_memattr_get_best_target(hwloc_topology_t topology,
-
320  hwloc_memattr_id_t attribute,
-
321  struct hwloc_location *initiator,
-
322  unsigned long flags,
-
323  hwloc_obj_t *best_target, hwloc_uint64_t *value);
-
324 
-
347 HWLOC_DECLSPEC int
-
348 hwloc_memattr_get_best_initiator(hwloc_topology_t topology,
-
349  hwloc_memattr_id_t attribute,
-
350  hwloc_obj_t target,
-
351  unsigned long flags,
-
352  struct hwloc_location *best_initiator, hwloc_uint64_t *value);
-
353 
-
363 HWLOC_DECLSPEC int
-
364 hwloc_memattr_get_name(hwloc_topology_t topology,
-
365  hwloc_memattr_id_t attribute,
-
366  const char **name);
-
367 
-
372 HWLOC_DECLSPEC int
-
373 hwloc_memattr_get_flags(hwloc_topology_t topology,
-
374  hwloc_memattr_id_t attribute,
-
375  unsigned long *flags);
-
376 
-
380 enum hwloc_memattr_flag_e {
-
384  HWLOC_MEMATTR_FLAG_HIGHER_FIRST = (1UL<<0),
-
388  HWLOC_MEMATTR_FLAG_LOWER_FIRST = (1UL<<1),
-
392  HWLOC_MEMATTR_FLAG_NEED_INITIATOR = (1UL<<2)
-
393 };
-
394 
-
401 HWLOC_DECLSPEC int
-
402 hwloc_memattr_register(hwloc_topology_t topology,
-
403  const char *name,
-
404  unsigned long flags,
-
405  hwloc_memattr_id_t *id);
-
406 
-
425 HWLOC_DECLSPEC int
-
426 hwloc_memattr_set_value(hwloc_topology_t topology,
-
427  hwloc_memattr_id_t attribute,
-
428  hwloc_obj_t target_node,
-
429  struct hwloc_location *initiator,
-
430  unsigned long flags,
-
431  hwloc_uint64_t value);
-
432 
-
469 HWLOC_DECLSPEC int
-
470 hwloc_memattr_get_targets(hwloc_topology_t topology,
-
471  hwloc_memattr_id_t attribute,
-
472  struct hwloc_location *initiator,
-
473  unsigned long flags,
-
474  unsigned *nr, hwloc_obj_t *targets, hwloc_uint64_t *values);
-
475 
-
505 HWLOC_DECLSPEC int
-
506 hwloc_memattr_get_initiators(hwloc_topology_t topology,
-
507  hwloc_memattr_id_t attribute,
-
508  hwloc_obj_t target_node,
-
509  unsigned long flags,
-
510  unsigned *nr, struct hwloc_location *initiators, hwloc_uint64_t *values);
-
513 #ifdef __cplusplus
-
514 } /* extern "C" */
-
515 #endif
-
516 
-
517 
-
518 #endif /* HWLOC_MEMATTR_H */
-
hwloc_cpuset_t
hwloc_bitmap_t hwloc_cpuset_t
A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
Definition: hwloc.h:140
-
hwloc_topology_t
struct hwloc_topology * hwloc_topology_t
Topology context.
Definition: hwloc.h:692
-
hwloc_memattr_get_value
int hwloc_memattr_get_value(hwloc_topology_t topology, hwloc_memattr_id_t attribute, hwloc_obj_t target_node, struct hwloc_location *initiator, unsigned long flags, hwloc_uint64_t *value)
Return an attribute value for a specific target NUMA node.
-
hwloc_location_type_e
hwloc_location_type_e
Type of location.
Definition: memattrs.h:189
-
hwloc_get_local_numanode_objs
int hwloc_get_local_numanode_objs(hwloc_topology_t topology, struct hwloc_location *location, unsigned *nr, hwloc_obj_t *nodes, unsigned long flags)
Return an array of local NUMA nodes.
-
hwloc_memattr_get_by_name
int hwloc_memattr_get_by_name(hwloc_topology_t topology, const char *name, hwloc_memattr_id_t *id)
Return the identifier of the memory attribute with the given name.
-
hwloc_memattr_get_best_target
int hwloc_memattr_get_best_target(hwloc_topology_t topology, hwloc_memattr_id_t attribute, struct hwloc_location *initiator, unsigned long flags, hwloc_obj_t *best_target, hwloc_uint64_t *value)
Return the best target NUMA node for the given attribute and initiator.
-
hwloc_memattr_get_best_initiator
int hwloc_memattr_get_best_initiator(hwloc_topology_t topology, hwloc_memattr_id_t attribute, hwloc_obj_t target, unsigned long flags, struct hwloc_location *best_initiator, hwloc_uint64_t *value)
Return the best initiator for the given attribute and target NUMA node.
-
hwloc_memattr_id_e
hwloc_memattr_id_e
Memory node attributes.
Definition: memattrs.h:69
-
hwloc_local_numanode_flag_e
hwloc_local_numanode_flag_e
Flags for selecting target NUMA nodes.
Definition: memattrs.h:211
-
hwloc_memattr_id_t
unsigned hwloc_memattr_id_t
A memory attribute identifier. May be either one of hwloc_memattr_id_e or a new id returned by hwloc_...
Definition: memattrs.h:178
-
HWLOC_LOCATION_TYPE_CPUSET
@ HWLOC_LOCATION_TYPE_CPUSET
Location is given as a cpuset, in the location cpuset union field.
Definition: memattrs.h:191
-
HWLOC_LOCATION_TYPE_OBJECT
@ HWLOC_LOCATION_TYPE_OBJECT
Location is given as an object, in the location object union field.
Definition: memattrs.h:193
-
HWLOC_MEMATTR_ID_BANDWIDTH
@ HWLOC_MEMATTR_ID_BANDWIDTH
The "Bandwidth" is returned in MiB/s, as seen from the given initiator location.
Definition: memattrs.h:109
-
HWLOC_MEMATTR_ID_WRITE_BANDWIDTH
@ HWLOC_MEMATTR_ID_WRITE_BANDWIDTH
The "WriteBandwidth" is returned in MiB/s, as seen from the given initiator location.
Definition: memattrs.h:131
-
HWLOC_MEMATTR_ID_READ_LATENCY
@ HWLOC_MEMATTR_ID_READ_LATENCY
The "ReadLatency" is returned as nanoseconds, as seen from the given initiator location.
Definition: memattrs.h:157
-
HWLOC_MEMATTR_ID_LOCALITY
@ HWLOC_MEMATTR_ID_LOCALITY
The "Locality" is returned as the number of PUs in that locality (e.g. the weight of its cpuset).
Definition: memattrs.h:94
-
HWLOC_MEMATTR_ID_CAPACITY
@ HWLOC_MEMATTR_ID_CAPACITY
The "Capacity" is returned in bytes (local_memory attribute in objects).
Definition: memattrs.h:79
-
HWLOC_MEMATTR_ID_WRITE_LATENCY
@ HWLOC_MEMATTR_ID_WRITE_LATENCY
The "WriteLatency" is returned as nanoseconds, as seen from the given initiator location.
Definition: memattrs.h:168
-
HWLOC_MEMATTR_ID_READ_BANDWIDTH
@ HWLOC_MEMATTR_ID_READ_BANDWIDTH
The "ReadBandwidth" is returned in MiB/s, as seen from the given initiator location.
Definition: memattrs.h:120
-
HWLOC_MEMATTR_ID_LATENCY
@ HWLOC_MEMATTR_ID_LATENCY
The "Latency" is returned as nanoseconds, as seen from the given initiator location.
Definition: memattrs.h:146
-
HWLOC_LOCAL_NUMANODE_FLAG_LARGER_LOCALITY
@ HWLOC_LOCAL_NUMANODE_FLAG_LARGER_LOCALITY
Select NUMA nodes whose locality is larger than the given cpuset. For instance, if a single PU (or it...
Definition: memattrs.h:217
-
HWLOC_LOCAL_NUMANODE_FLAG_SMALLER_LOCALITY
@ HWLOC_LOCAL_NUMANODE_FLAG_SMALLER_LOCALITY
Select NUMA nodes whose locality is smaller than the given cpuset. For instance, if a package (or its...
Definition: memattrs.h:224
-
HWLOC_LOCAL_NUMANODE_FLAG_ALL
@ HWLOC_LOCAL_NUMANODE_FLAG_ALL
Select all NUMA nodes in the topology. The initiator initiator is ignored.
Definition: memattrs.h:230
-
hwloc_memattr_get_initiators
int hwloc_memattr_get_initiators(hwloc_topology_t topology, hwloc_memattr_id_t attribute, hwloc_obj_t target_node, unsigned long flags, unsigned *nr, struct hwloc_location *initiators, hwloc_uint64_t *values)
Return the initiators that have values for a given attribute for a specific target NUMA node.
-
hwloc_memattr_get_flags
int hwloc_memattr_get_flags(hwloc_topology_t topology, hwloc_memattr_id_t attribute, unsigned long *flags)
Return the flags of the given attribute.
-
hwloc_memattr_get_name
int hwloc_memattr_get_name(hwloc_topology_t topology, hwloc_memattr_id_t attribute, const char **name)
Return the name of a memory attribute.
-
hwloc_memattr_register
int hwloc_memattr_register(hwloc_topology_t topology, const char *name, unsigned long flags, hwloc_memattr_id_t *id)
Register a new memory attribute.
-
hwloc_memattr_flag_e
hwloc_memattr_flag_e
Memory attribute flags. Given to hwloc_memattr_register() and returned by hwloc_memattr_get_flags().
Definition: memattrs.h:380
-
hwloc_memattr_set_value
int hwloc_memattr_set_value(hwloc_topology_t topology, hwloc_memattr_id_t attribute, hwloc_obj_t target_node, struct hwloc_location *initiator, unsigned long flags, hwloc_uint64_t value)
Set an attribute value for a specific target NUMA node.
-
hwloc_memattr_get_targets
int hwloc_memattr_get_targets(hwloc_topology_t topology, hwloc_memattr_id_t attribute, struct hwloc_location *initiator, unsigned long flags, unsigned *nr, hwloc_obj_t *targets, hwloc_uint64_t *values)
Return the target NUMA nodes that have some values for a given attribute.
-
HWLOC_MEMATTR_FLAG_LOWER_FIRST
@ HWLOC_MEMATTR_FLAG_LOWER_FIRST
The best nodes for this memory attribute are those with the lower values. For instance Latency.
Definition: memattrs.h:388
-
HWLOC_MEMATTR_FLAG_NEED_INITIATOR
@ HWLOC_MEMATTR_FLAG_NEED_INITIATOR
The value returned for this memory attribute depends on the given initiator. For instance Bandwidth a...
Definition: memattrs.h:392
-
HWLOC_MEMATTR_FLAG_HIGHER_FIRST
@ HWLOC_MEMATTR_FLAG_HIGHER_FIRST
The best nodes for this memory attribute are those with the higher values. For instance Bandwidth.
Definition: memattrs.h:384
-
hwloc_obj
Structure of a topology object.
Definition: hwloc.h:396
-
hwloc_location
Where to measure attributes from.
Definition: memattrs.h:197
-
hwloc_location::location
union hwloc_location::hwloc_location_u location
-
hwloc_location::type
enum hwloc_location_type_e type
Type of location.
Definition: memattrs.h:199
-
hwloc_location::hwloc_location_u
Actual location.
Definition: memattrs.h:201
-
hwloc_location::hwloc_location_u::cpuset
hwloc_cpuset_t cpuset
Location as a cpuset, when the location type is HWLOC_LOCATION_TYPE_CPUSET.
Definition: memattrs.h:203
-
hwloc_location::hwloc_location_u::object
hwloc_obj_t object
Location as an object, when the location type is HWLOC_LOCATION_TYPE_OBJECT.
Definition: memattrs.h:205
-
- - - - - - - - -
-
-
cpukinds.h
-
-
-
1 /*
-
2  * Copyright © 2020-2021 Inria. All rights reserved.
-
3  * See COPYING in top-level directory.
-
4  */
-
5 
-
10 #ifndef HWLOC_CPUKINDS_H
-
11 #define HWLOC_CPUKINDS_H
-
12 
-
13 #include "hwloc.h"
-
14 
-
15 #ifdef __cplusplus
-
16 extern "C" {
-
17 #elif 0
-
18 }
-
19 #endif
-
20 
-
81 HWLOC_DECLSPEC int
-
82 hwloc_cpukinds_get_nr(hwloc_topology_t topology,
-
83  unsigned long flags);
-
84 
-
96 HWLOC_DECLSPEC int
-
97 hwloc_cpukinds_get_by_cpuset(hwloc_topology_t topology,
-
98  hwloc_const_bitmap_t cpuset,
-
99  unsigned long flags);
-
100 
-
134 HWLOC_DECLSPEC int
-
135 hwloc_cpukinds_get_info(hwloc_topology_t topology,
-
136  unsigned kind_index,
-
137  hwloc_bitmap_t cpuset,
-
138  int *efficiency,
-
139  unsigned *nr_infos, struct hwloc_info_s **infos,
-
140  unsigned long flags);
-
141 
-
179 HWLOC_DECLSPEC int
-
180 hwloc_cpukinds_register(hwloc_topology_t topology,
-
181  hwloc_bitmap_t cpuset,
-
182  int forced_efficiency,
-
183  unsigned nr_infos, struct hwloc_info_s *infos,
-
184  unsigned long flags);
-
185 
-
188 #ifdef __cplusplus
-
189 } /* extern "C" */
-
190 #endif
-
191 
-
192 
-
193 #endif /* HWLOC_CPUKINDS_H */
-
hwloc_topology_t
struct hwloc_topology * hwloc_topology_t
Topology context.
Definition: hwloc.h:692
-
hwloc_bitmap_t
struct hwloc_bitmap_s * hwloc_bitmap_t
Set of bits represented as an opaque pointer to an internal bitmap.
Definition: bitmap.h:68
-
hwloc_const_bitmap_t
const struct hwloc_bitmap_s * hwloc_const_bitmap_t
a non-modifiable hwloc_bitmap_t
Definition: bitmap.h:70
-
hwloc_cpukinds_register
int hwloc_cpukinds_register(hwloc_topology_t topology, hwloc_bitmap_t cpuset, int forced_efficiency, unsigned nr_infos, struct hwloc_info_s *infos, unsigned long flags)
Register a kind of CPU in the topology.
-
hwloc_cpukinds_get_nr
int hwloc_cpukinds_get_nr(hwloc_topology_t topology, unsigned long flags)
Get the number of different kinds of CPU cores in the topology.
-
hwloc_cpukinds_get_info
int hwloc_cpukinds_get_info(hwloc_topology_t topology, unsigned kind_index, hwloc_bitmap_t cpuset, int *efficiency, unsigned *nr_infos, struct hwloc_info_s **infos, unsigned long flags)
Get the CPU set and infos about a CPU kind in the topology.
-
hwloc_cpukinds_get_by_cpuset
int hwloc_cpukinds_get_by_cpuset(hwloc_topology_t topology, hwloc_const_bitmap_t cpuset, unsigned long flags)
Get the index of the CPU kind that contains CPUs listed in cpuset.
-
hwloc_info_s
Object info.
Definition: hwloc.h:674
-
- - - - - - - - -
-
-
linux.h
-
-
-
1 /*
-
2  * Copyright © 2009 CNRS
-
3  * Copyright © 2009-2021 Inria. All rights reserved.
-
4  * Copyright © 2009-2011 Université Bordeaux
-
5  * See COPYING in top-level directory.
-
6  */
-
7 
-
15 #ifndef HWLOC_LINUX_H
-
16 #define HWLOC_LINUX_H
-
17 
-
18 #include "hwloc.h"
-
19 
-
20 #include <stdio.h>
-
21 
-
22 
-
23 #ifdef __cplusplus
-
24 extern "C" {
-
25 #endif
-
26 
-
27 
-
44 HWLOC_DECLSPEC int hwloc_linux_set_tid_cpubind(hwloc_topology_t topology, pid_t tid, hwloc_const_cpuset_t set);
-
45 
-
58 HWLOC_DECLSPEC int hwloc_linux_get_tid_cpubind(hwloc_topology_t topology, pid_t tid, hwloc_cpuset_t set);
-
59 
-
68 HWLOC_DECLSPEC int hwloc_linux_get_tid_last_cpu_location(hwloc_topology_t topology, pid_t tid, hwloc_bitmap_t set);
-
69 
-
77 HWLOC_DECLSPEC int hwloc_linux_read_path_as_cpumask(const char *path, hwloc_bitmap_t set);
-
78 
-
82 #ifdef __cplusplus
-
83 } /* extern "C" */
-
84 #endif
-
85 
-
86 
-
87 #endif /* HWLOC_LINUX_H */
-
hwloc_const_cpuset_t
hwloc_const_bitmap_t hwloc_const_cpuset_t
A non-modifiable hwloc_cpuset_t.
Definition: hwloc.h:142
-
hwloc_cpuset_t
hwloc_bitmap_t hwloc_cpuset_t
A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
Definition: hwloc.h:140
-
hwloc_topology_t
struct hwloc_topology * hwloc_topology_t
Topology context.
Definition: hwloc.h:692
-
hwloc_bitmap_t
struct hwloc_bitmap_s * hwloc_bitmap_t
Set of bits represented as an opaque pointer to an internal bitmap.
Definition: bitmap.h:68
-
hwloc_linux_set_tid_cpubind
int hwloc_linux_set_tid_cpubind(hwloc_topology_t topology, pid_t tid, hwloc_const_cpuset_t set)
Bind a thread tid on cpus given in cpuset set.
-
hwloc_linux_get_tid_last_cpu_location
int hwloc_linux_get_tid_last_cpu_location(hwloc_topology_t topology, pid_t tid, hwloc_bitmap_t set)
Get the last physical CPU where thread tid ran.
-
hwloc_linux_get_tid_cpubind
int hwloc_linux_get_tid_cpubind(hwloc_topology_t topology, pid_t tid, hwloc_cpuset_t set)
Get the current binding of thread tid.
-
hwloc_linux_read_path_as_cpumask
int hwloc_linux_read_path_as_cpumask(const char *path, hwloc_bitmap_t set)
Convert a linux kernel cpumask file path into a hwloc bitmap set.
-
- - - - - - - - -
-
-
linux-libnuma.h
-
-
-
1 /*
-
2  * Copyright © 2009 CNRS
-
3  * Copyright © 2009-2017 Inria. All rights reserved.
-
4  * Copyright © 2009-2010, 2012 Université Bordeaux
-
5  * See COPYING in top-level directory.
-
6  */
-
7 
-
15 #ifndef HWLOC_LINUX_LIBNUMA_H
-
16 #define HWLOC_LINUX_LIBNUMA_H
-
17 
-
18 #include "hwloc.h"
-
19 
-
20 #include <numa.h>
-
21 
-
22 
-
23 #ifdef __cplusplus
-
24 extern "C" {
-
25 #endif
-
26 
-
27 
-
54 static __hwloc_inline int
-
55 hwloc_cpuset_to_linux_libnuma_ulongs(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset,
-
56  unsigned long *mask, unsigned long *maxnode)
-
57 {
-
58  int depth = hwloc_get_type_depth(topology, HWLOC_OBJ_NUMANODE);
-
59  unsigned long outmaxnode = -1;
-
60  hwloc_obj_t node = NULL;
-
61 
-
62  /* round-up to the next ulong and clear all bytes */
-
63  *maxnode = (*maxnode + 8*sizeof(*mask) - 1) & ~(8*sizeof(*mask) - 1);
-
64  memset(mask, 0, *maxnode/8);
-
65 
-
66  while ((node = hwloc_get_next_obj_covering_cpuset_by_depth(topology, cpuset, depth, node)) != NULL) {
-
67  if (node->os_index >= *maxnode)
-
68  continue;
-
69  mask[node->os_index/sizeof(*mask)/8] |= 1UL << (node->os_index % (sizeof(*mask)*8));
-
70  if (outmaxnode == (unsigned long) -1 || outmaxnode < node->os_index)
-
71  outmaxnode = node->os_index;
-
72  }
-
73 
-
74  *maxnode = outmaxnode+1;
-
75  return 0;
-
76 }
-
77 
-
88 static __hwloc_inline int
-
89 hwloc_nodeset_to_linux_libnuma_ulongs(hwloc_topology_t topology, hwloc_const_nodeset_t nodeset,
-
90  unsigned long *mask, unsigned long *maxnode)
-
91 {
-
92  int depth = hwloc_get_type_depth(topology, HWLOC_OBJ_NUMANODE);
-
93  unsigned long outmaxnode = -1;
-
94  hwloc_obj_t node = NULL;
-
95 
-
96  /* round-up to the next ulong and clear all bytes */
-
97  *maxnode = (*maxnode + 8*sizeof(*mask) - 1) & ~(8*sizeof(*mask) - 1);
-
98  memset(mask, 0, *maxnode/8);
-
99 
-
100  while ((node = hwloc_get_next_obj_by_depth(topology, depth, node)) != NULL) {
-
101  if (node->os_index >= *maxnode)
-
102  continue;
-
103  if (!hwloc_bitmap_isset(nodeset, node->os_index))
-
104  continue;
-
105  mask[node->os_index/sizeof(*mask)/8] |= 1UL << (node->os_index % (sizeof(*mask)*8));
-
106  if (outmaxnode == (unsigned long) -1 || outmaxnode < node->os_index)
-
107  outmaxnode = node->os_index;
-
108  }
-
109 
-
110  *maxnode = outmaxnode+1;
-
111  return 0;
-
112 }
-
113 
-
123 static __hwloc_inline int
-
124 hwloc_cpuset_from_linux_libnuma_ulongs(hwloc_topology_t topology, hwloc_cpuset_t cpuset,
-
125  const unsigned long *mask, unsigned long maxnode)
-
126 {
-
127  int depth = hwloc_get_type_depth(topology, HWLOC_OBJ_NUMANODE);
-
128  hwloc_obj_t node = NULL;
-
129  hwloc_bitmap_zero(cpuset);
-
130  while ((node = hwloc_get_next_obj_by_depth(topology, depth, node)) != NULL)
-
131  if (node->os_index < maxnode
-
132  && (mask[node->os_index/sizeof(*mask)/8] & (1UL << (node->os_index % (sizeof(*mask)*8)))))
-
133  hwloc_bitmap_or(cpuset, cpuset, node->cpuset);
-
134  return 0;
-
135 }
-
136 
-
146 static __hwloc_inline int
-
147 hwloc_nodeset_from_linux_libnuma_ulongs(hwloc_topology_t topology, hwloc_nodeset_t nodeset,
-
148  const unsigned long *mask, unsigned long maxnode)
-
149 {
-
150  int depth = hwloc_get_type_depth(topology, HWLOC_OBJ_NUMANODE);
-
151  hwloc_obj_t node = NULL;
-
152  hwloc_bitmap_zero(nodeset);
-
153  while ((node = hwloc_get_next_obj_by_depth(topology, depth, node)) != NULL)
-
154  if (node->os_index < maxnode
-
155  && (mask[node->os_index/sizeof(*mask)/8] & (1UL << (node->os_index % (sizeof(*mask)*8)))))
-
156  hwloc_bitmap_set(nodeset, node->os_index);
-
157  return 0;
-
158 }
-
159 
-
189 static __hwloc_inline struct bitmask *
-
190 hwloc_cpuset_to_linux_libnuma_bitmask(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset) __hwloc_attribute_malloc;
-
191 static __hwloc_inline struct bitmask *
-
192 hwloc_cpuset_to_linux_libnuma_bitmask(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset)
-
193 {
-
194  int depth = hwloc_get_type_depth(topology, HWLOC_OBJ_NUMANODE);
-
195  hwloc_obj_t node = NULL;
-
196  struct bitmask *bitmask = numa_allocate_cpumask();
-
197  if (!bitmask)
-
198  return NULL;
-
199  while ((node = hwloc_get_next_obj_covering_cpuset_by_depth(topology, cpuset, depth, node)) != NULL)
-
200  if (node->attr->numanode.local_memory)
-
201  numa_bitmask_setbit(bitmask, node->os_index);
-
202  return bitmask;
-
203 }
-
204 
-
214 static __hwloc_inline struct bitmask *
-
215 hwloc_nodeset_to_linux_libnuma_bitmask(hwloc_topology_t topology, hwloc_const_nodeset_t nodeset) __hwloc_attribute_malloc;
-
216 static __hwloc_inline struct bitmask *
-
217 hwloc_nodeset_to_linux_libnuma_bitmask(hwloc_topology_t topology, hwloc_const_nodeset_t nodeset)
-
218 {
-
219  int depth = hwloc_get_type_depth(topology, HWLOC_OBJ_NUMANODE);
-
220  hwloc_obj_t node = NULL;
-
221  struct bitmask *bitmask = numa_allocate_cpumask();
-
222  if (!bitmask)
-
223  return NULL;
-
224  while ((node = hwloc_get_next_obj_by_depth(topology, depth, node)) != NULL)
-
225  if (hwloc_bitmap_isset(nodeset, node->os_index) && node->attr->numanode.local_memory)
-
226  numa_bitmask_setbit(bitmask, node->os_index);
-
227  return bitmask;
-
228 }
-
229 
-
235 static __hwloc_inline int
-
236 hwloc_cpuset_from_linux_libnuma_bitmask(hwloc_topology_t topology, hwloc_cpuset_t cpuset,
-
237  const struct bitmask *bitmask)
-
238 {
-
239  int depth = hwloc_get_type_depth(topology, HWLOC_OBJ_NUMANODE);
-
240  hwloc_obj_t node = NULL;
-
241  hwloc_bitmap_zero(cpuset);
-
242  while ((node = hwloc_get_next_obj_by_depth(topology, depth, node)) != NULL)
-
243  if (numa_bitmask_isbitset(bitmask, node->os_index))
-
244  hwloc_bitmap_or(cpuset, cpuset, node->cpuset);
-
245  return 0;
-
246 }
-
247 
-
253 static __hwloc_inline int
-
254 hwloc_nodeset_from_linux_libnuma_bitmask(hwloc_topology_t topology, hwloc_nodeset_t nodeset,
-
255  const struct bitmask *bitmask)
-
256 {
-
257  int depth = hwloc_get_type_depth(topology, HWLOC_OBJ_NUMANODE);
-
258  hwloc_obj_t node = NULL;
-
259  hwloc_bitmap_zero(nodeset);
-
260  while ((node = hwloc_get_next_obj_by_depth(topology, depth, node)) != NULL)
-
261  if (numa_bitmask_isbitset(bitmask, node->os_index))
-
262  hwloc_bitmap_set(nodeset, node->os_index);
-
263  return 0;
-
264 }
-
265 
-
269 #ifdef __cplusplus
-
270 } /* extern "C" */
-
271 #endif
-
272 
-
273 
-
274 #endif /* HWLOC_LINUX_NUMA_H */
-
hwloc_const_cpuset_t
hwloc_const_bitmap_t hwloc_const_cpuset_t
A non-modifiable hwloc_cpuset_t.
Definition: hwloc.h:142
-
hwloc_const_nodeset_t
hwloc_const_bitmap_t hwloc_const_nodeset_t
A non-modifiable hwloc_nodeset_t.
Definition: hwloc.h:160
-
hwloc_nodeset_t
hwloc_bitmap_t hwloc_nodeset_t
A node set is a bitmap whose bits are set according to NUMA memory node physical OS indexes.
Definition: hwloc.h:157
-
hwloc_cpuset_t
hwloc_bitmap_t hwloc_cpuset_t
A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
Definition: hwloc.h:140
-
HWLOC_OBJ_NUMANODE
@ HWLOC_OBJ_NUMANODE
NUMA node. An object that contains memory that is directly and byte-accessible to the host processors...
Definition: hwloc.h:236
-
hwloc_topology_t
struct hwloc_topology * hwloc_topology_t
Topology context.
Definition: hwloc.h:692
-
hwloc_get_type_depth
int hwloc_get_type_depth(hwloc_topology_t topology, hwloc_obj_type_t type)
Returns the depth of objects of type type.
-
hwloc_get_next_obj_by_depth
static hwloc_obj_t hwloc_get_next_obj_by_depth(hwloc_topology_t topology, int depth, hwloc_obj_t prev)
Returns the next object at depth depth.
-
hwloc_get_next_obj_covering_cpuset_by_depth
static hwloc_obj_t hwloc_get_next_obj_covering_cpuset_by_depth(hwloc_topology_t topology, hwloc_const_cpuset_t set, int depth, hwloc_obj_t prev)
Iterate through same-depth objects covering at least CPU set set.
Definition: helper.h:321
-
hwloc_bitmap_set
int hwloc_bitmap_set(hwloc_bitmap_t bitmap, unsigned id)
Add index id in bitmap bitmap.
-
hwloc_bitmap_isset
int hwloc_bitmap_isset(hwloc_const_bitmap_t bitmap, unsigned id)
Test whether index id is part of bitmap bitmap.
-
hwloc_bitmap_or
int hwloc_bitmap_or(hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
Or bitmaps bitmap1 and bitmap2 and store the result in bitmap res.
-
hwloc_bitmap_zero
void hwloc_bitmap_zero(hwloc_bitmap_t bitmap)
Empty the bitmap bitmap.
-
hwloc_cpuset_from_linux_libnuma_ulongs
static int hwloc_cpuset_from_linux_libnuma_ulongs(hwloc_topology_t topology, hwloc_cpuset_t cpuset, const unsigned long *mask, unsigned long maxnode)
Convert the array of unsigned long mask into hwloc CPU set.
Definition: linux-libnuma.h:124
-
hwloc_nodeset_to_linux_libnuma_ulongs
static int hwloc_nodeset_to_linux_libnuma_ulongs(hwloc_topology_t topology, hwloc_const_nodeset_t nodeset, unsigned long *mask, unsigned long *maxnode)
Convert hwloc NUMA node set nodeset into the array of unsigned long mask.
Definition: linux-libnuma.h:89
-
hwloc_nodeset_from_linux_libnuma_ulongs
static int hwloc_nodeset_from_linux_libnuma_ulongs(hwloc_topology_t topology, hwloc_nodeset_t nodeset, const unsigned long *mask, unsigned long maxnode)
Convert the array of unsigned long mask into hwloc NUMA node set.
Definition: linux-libnuma.h:147
-
hwloc_cpuset_to_linux_libnuma_ulongs
static int hwloc_cpuset_to_linux_libnuma_ulongs(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, unsigned long *mask, unsigned long *maxnode)
Convert hwloc CPU set cpuset into the array of unsigned long mask.
Definition: linux-libnuma.h:55
-
hwloc_cpuset_from_linux_libnuma_bitmask
static int hwloc_cpuset_from_linux_libnuma_bitmask(hwloc_topology_t topology, hwloc_cpuset_t cpuset, const struct bitmask *bitmask)
Convert libnuma bitmask bitmask into hwloc CPU set cpuset.
Definition: linux-libnuma.h:236
-
hwloc_nodeset_from_linux_libnuma_bitmask
static int hwloc_nodeset_from_linux_libnuma_bitmask(hwloc_topology_t topology, hwloc_nodeset_t nodeset, const struct bitmask *bitmask)
Convert libnuma bitmask bitmask into hwloc NUMA node set nodeset.
Definition: linux-libnuma.h:254
-
hwloc_cpuset_to_linux_libnuma_bitmask
static struct bitmask * hwloc_cpuset_to_linux_libnuma_bitmask(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset)
Convert hwloc CPU set cpuset into the returned libnuma bitmask.
Definition: linux-libnuma.h:192
-
hwloc_nodeset_to_linux_libnuma_bitmask
static struct bitmask * hwloc_nodeset_to_linux_libnuma_bitmask(hwloc_topology_t topology, hwloc_const_nodeset_t nodeset)
Convert hwloc NUMA node set nodeset into the returned libnuma bitmask.
Definition: linux-libnuma.h:217
-
hwloc_obj
Structure of a topology object.
Definition: hwloc.h:396
-
hwloc_obj::os_index
unsigned os_index
OS-provided physical index number. It is not guaranteed unique across the entire machine,...
Definition: hwloc.h:401
-
hwloc_obj::cpuset
hwloc_cpuset_t cpuset
CPUs covered by this object.
Definition: hwloc.h:512
-
hwloc_obj::attr
union hwloc_obj_attr_u * attr
Object type-specific Attributes, may be NULL if no attribute value was found.
Definition: hwloc.h:415
-
hwloc_obj_attr_u::numanode
struct hwloc_obj_attr_u::hwloc_numanode_attr_s numanode
-
hwloc_obj_attr_u::hwloc_numanode_attr_s::local_memory
hwloc_uint64_t local_memory
Local memory (in bytes)
Definition: hwloc.h:602
-
- - - - - - - - -
-
-
windows.h
-
-
-
1 /*
-
2  * Copyright © 2021 Inria. All rights reserved.
-
3  * See COPYING in top-level directory.
-
4  */
-
5 
-
13 #ifndef HWLOC_WINDOWS_H
-
14 #define HWLOC_WINDOWS_H
-
15 
-
16 #include "hwloc.h"
-
17 
-
18 
-
19 #ifdef __cplusplus
-
20 extern "C" {
-
21 #endif
-
22 
-
23 
-
50 HWLOC_DECLSPEC int hwloc_windows_get_nr_processor_groups(hwloc_topology_t topology, unsigned long flags);
-
51 
-
66 HWLOC_DECLSPEC int hwloc_windows_get_processor_group_cpuset(hwloc_topology_t topology, unsigned pg_index, hwloc_cpuset_t cpuset, unsigned long flags);
-
67 
-
71 #ifdef __cplusplus
-
72 } /* extern "C" */
-
73 #endif
-
74 
-
75 
-
76 #endif /* HWLOC_WINDOWS_H */
-
hwloc_cpuset_t
hwloc_bitmap_t hwloc_cpuset_t
A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
Definition: hwloc.h:140
-
hwloc_topology_t
struct hwloc_topology * hwloc_topology_t
Topology context.
Definition: hwloc.h:692
-
hwloc_windows_get_processor_group_cpuset
int hwloc_windows_get_processor_group_cpuset(hwloc_topology_t topology, unsigned pg_index, hwloc_cpuset_t cpuset, unsigned long flags)
Get the CPU-set of a Windows processor group.
-
hwloc_windows_get_nr_processor_groups
int hwloc_windows_get_nr_processor_groups(hwloc_topology_t topology, unsigned long flags)
Get the number of Windows processor groups.
-
- - - - - - - - -
-
-
glibc-sched.h
-
-
-
1 /*
-
2  * Copyright © 2009 CNRS
-
3  * Copyright © 2009-2020 Inria. All rights reserved.
-
4  * Copyright © 2009-2011 Université Bordeaux
-
5  * Copyright © 2011 Cisco Systems, Inc. All rights reserved.
-
6  * See COPYING in top-level directory.
-
7  */
-
8 
-
17 #ifndef HWLOC_GLIBC_SCHED_H
-
18 #define HWLOC_GLIBC_SCHED_H
-
19 
-
20 #include "hwloc.h"
-
21 #include "hwloc/helper.h"
-
22 
-
23 #include <assert.h>
-
24 
-
25 #if !defined _GNU_SOURCE || (!defined _SCHED_H && !defined _SCHED_H_) || (!defined CPU_SETSIZE && !defined sched_priority)
-
26 #error Please make sure to include sched.h before including glibc-sched.h, and define _GNU_SOURCE before any inclusion of sched.h
-
27 #endif
-
28 
-
29 
-
30 #ifdef __cplusplus
-
31 extern "C" {
-
32 #endif
-
33 
-
34 
-
35 #ifdef HWLOC_HAVE_CPU_SET
-
36 
-
37 
-
56 static __hwloc_inline int
-
57 hwloc_cpuset_to_glibc_sched_affinity(hwloc_topology_t topology __hwloc_attribute_unused, hwloc_const_cpuset_t hwlocset,
-
58  cpu_set_t *schedset, size_t schedsetsize)
-
59 {
-
60 #ifdef CPU_ZERO_S
-
61  unsigned cpu;
-
62  CPU_ZERO_S(schedsetsize, schedset);
-
63  hwloc_bitmap_foreach_begin(cpu, hwlocset)
-
64  CPU_SET_S(cpu, schedsetsize, schedset);
-
65  hwloc_bitmap_foreach_end();
-
66 #else /* !CPU_ZERO_S */
-
67  unsigned cpu;
-
68  CPU_ZERO(schedset);
-
69  assert(schedsetsize == sizeof(cpu_set_t));
-
70  hwloc_bitmap_foreach_begin(cpu, hwlocset)
-
71  CPU_SET(cpu, schedset);
-
72  hwloc_bitmap_foreach_end();
-
73 #endif /* !CPU_ZERO_S */
-
74  return 0;
-
75 }
-
76 
-
84 static __hwloc_inline int
-
85 hwloc_cpuset_from_glibc_sched_affinity(hwloc_topology_t topology __hwloc_attribute_unused, hwloc_cpuset_t hwlocset,
-
86  const cpu_set_t *schedset, size_t schedsetsize)
-
87 {
-
88  int cpu;
-
89 #ifdef CPU_ZERO_S
-
90  int count;
-
91 #endif
-
92  hwloc_bitmap_zero(hwlocset);
-
93 #ifdef CPU_ZERO_S
-
94  count = CPU_COUNT_S(schedsetsize, schedset);
-
95  cpu = 0;
-
96  while (count) {
-
97  if (CPU_ISSET_S(cpu, schedsetsize, schedset)) {
-
98  hwloc_bitmap_set(hwlocset, cpu);
-
99  count--;
-
100  }
-
101  cpu++;
-
102  }
-
103 #else /* !CPU_ZERO_S */
-
104  /* sched.h does not support dynamic cpu_set_t (introduced in glibc 2.7),
-
105  * assume we have a very old interface without CPU_COUNT (added in 2.6)
-
106  */
-
107  assert(schedsetsize == sizeof(cpu_set_t));
-
108  for(cpu=0; cpu<CPU_SETSIZE; cpu++)
-
109  if (CPU_ISSET(cpu, schedset))
-
110  hwloc_bitmap_set(hwlocset, cpu);
-
111 #endif /* !CPU_ZERO_S */
-
112  return 0;
-
113 }
-
114 
-
118 #endif /* CPU_SET */
-
119 
-
120 
-
121 #ifdef __cplusplus
-
122 } /* extern "C" */
-
123 #endif
-
124 
-
125 
-
126 #endif /* HWLOC_GLIBC_SCHED_H */
-
hwloc_const_cpuset_t
hwloc_const_bitmap_t hwloc_const_cpuset_t
A non-modifiable hwloc_cpuset_t.
Definition: hwloc.h:142
-
hwloc_cpuset_t
hwloc_bitmap_t hwloc_cpuset_t
A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
Definition: hwloc.h:140
-
hwloc_topology_t
struct hwloc_topology * hwloc_topology_t
Topology context.
Definition: hwloc.h:692
-
hwloc_bitmap_set
int hwloc_bitmap_set(hwloc_bitmap_t bitmap, unsigned id)
Add index id in bitmap bitmap.
-
hwloc_bitmap_foreach_begin
#define hwloc_bitmap_foreach_begin(id, bitmap)
Loop macro iterating on bitmap bitmap.
Definition: bitmap.h:370
-
hwloc_bitmap_zero
void hwloc_bitmap_zero(hwloc_bitmap_t bitmap)
Empty the bitmap bitmap.
-
hwloc_bitmap_foreach_end
#define hwloc_bitmap_foreach_end()
End of loop macro iterating on a bitmap.
Definition: bitmap.h:384
-
hwloc_cpuset_to_glibc_sched_affinity
static int hwloc_cpuset_to_glibc_sched_affinity(hwloc_topology_t topology, hwloc_const_cpuset_t hwlocset, cpu_set_t *schedset, size_t schedsetsize)
Convert hwloc CPU set toposet into glibc sched affinity CPU set schedset.
Definition: glibc-sched.h:57
-
hwloc_cpuset_from_glibc_sched_affinity
static int hwloc_cpuset_from_glibc_sched_affinity(hwloc_topology_t topology, hwloc_cpuset_t hwlocset, const cpu_set_t *schedset, size_t schedsetsize)
Convert glibc sched affinity CPU set schedset into hwloc CPU set.
Definition: glibc-sched.h:85
-
- - - - - - - - -
-
-
opencl.h
-
-
-
1 /*
-
2  * Copyright © 2012-2021 Inria. All rights reserved.
-
3  * Copyright © 2013, 2018 Université Bordeaux. All right reserved.
-
4  * See COPYING in top-level directory.
-
5  */
-
6 
-
14 #ifndef HWLOC_OPENCL_H
-
15 #define HWLOC_OPENCL_H
-
16 
-
17 #include "hwloc.h"
-
18 #include "hwloc/autogen/config.h"
-
19 #include "hwloc/helper.h"
-
20 #ifdef HWLOC_LINUX_SYS
-
21 #include "hwloc/linux.h"
-
22 #endif
-
23 
-
24 #ifdef __APPLE__
-
25 #include <OpenCL/cl.h>
-
26 #else
-
27 #include <CL/cl.h>
-
28 #endif
-
29 
-
30 #include <stdio.h>
-
31 
-
32 
-
33 #ifdef __cplusplus
-
34 extern "C" {
-
35 #endif
-
36 
-
37 
-
38 /* OpenCL extensions aren't always shipped with default headers, and
-
39  * they don't always reflect what the installed implementations support.
-
40  * Try everything and let the implementation return errors when non supported.
-
41  */
-
42 /* Copyright (c) 2008-2018 The Khronos Group Inc. */
-
43 
-
44 /* needs "cl_amd_device_attribute_query" device extension, but not strictly required for clGetDeviceInfo() */
-
45 #define HWLOC_CL_DEVICE_TOPOLOGY_AMD 0x4037
-
46 typedef union {
-
47  struct { cl_uint type; cl_uint data[5]; } raw;
-
48  struct { cl_uint type; cl_char unused[17]; cl_char bus; cl_char device; cl_char function; } pcie;
-
49 } hwloc_cl_device_topology_amd;
-
50 #define HWLOC_CL_DEVICE_TOPOLOGY_TYPE_PCIE_AMD 1
-
51 
-
52 /* needs "cl_nv_device_attribute_query" device extension, but not strictly required for clGetDeviceInfo() */
-
53 #define HWLOC_CL_DEVICE_PCI_BUS_ID_NV 0x4008
-
54 #define HWLOC_CL_DEVICE_PCI_SLOT_ID_NV 0x4009
-
55 #define HWLOC_CL_DEVICE_PCI_DOMAIN_ID_NV 0x400A
-
56 
-
57 
-
73 static __hwloc_inline int
-
74 hwloc_opencl_get_device_pci_busid(cl_device_id device,
-
75  unsigned *domain, unsigned *bus, unsigned *dev, unsigned *func)
-
76 {
-
77  hwloc_cl_device_topology_amd amdtopo;
-
78  cl_uint nvbus, nvslot, nvdomain;
-
79  cl_int clret;
-
80 
-
81  clret = clGetDeviceInfo(device, HWLOC_CL_DEVICE_TOPOLOGY_AMD, sizeof(amdtopo), &amdtopo, NULL);
-
82  if (CL_SUCCESS == clret
-
83  && HWLOC_CL_DEVICE_TOPOLOGY_TYPE_PCIE_AMD == amdtopo.raw.type) {
-
84  *domain = 0; /* can't do anything better */
-
85  /* cl_device_topology_amd stores bus ID in cl_char, dont convert those signed char directly to unsigned int */
-
86  *bus = (unsigned) (unsigned char) amdtopo.pcie.bus;
-
87  *dev = (unsigned) (unsigned char) amdtopo.pcie.device;
-
88  *func = (unsigned) (unsigned char) amdtopo.pcie.function;
-
89  return 0;
-
90  }
-
91 
-
92  clret = clGetDeviceInfo(device, HWLOC_CL_DEVICE_PCI_BUS_ID_NV, sizeof(nvbus), &nvbus, NULL);
-
93  if (CL_SUCCESS == clret) {
-
94  clret = clGetDeviceInfo(device, HWLOC_CL_DEVICE_PCI_SLOT_ID_NV, sizeof(nvslot), &nvslot, NULL);
-
95  if (CL_SUCCESS == clret) {
-
96  clret = clGetDeviceInfo(device, HWLOC_CL_DEVICE_PCI_DOMAIN_ID_NV, sizeof(nvdomain), &nvdomain, NULL);
-
97  if (CL_SUCCESS == clret) { /* available since CUDA 10.2 */
-
98  *domain = nvdomain;
-
99  } else {
-
100  *domain = 0;
-
101  }
-
102  *bus = nvbus & 0xff;
-
103  /* non-documented but used in many other projects */
-
104  *dev = nvslot >> 3;
-
105  *func = nvslot & 0x7;
-
106  return 0;
-
107  }
-
108  }
-
109 
-
110  return -1;
-
111 }
-
112 
-
130 static __hwloc_inline int
-
131 hwloc_opencl_get_device_cpuset(hwloc_topology_t topology __hwloc_attribute_unused,
-
132  cl_device_id device __hwloc_attribute_unused,
-
133  hwloc_cpuset_t set)
-
134 {
-
135 #if (defined HWLOC_LINUX_SYS)
-
136  /* If we're on Linux, try AMD/NVIDIA extensions + the sysfs mechanism to get the local cpus */
-
137 #define HWLOC_OPENCL_DEVICE_SYSFS_PATH_MAX 128
-
138  char path[HWLOC_OPENCL_DEVICE_SYSFS_PATH_MAX];
-
139  unsigned pcidomain, pcibus, pcidev, pcifunc;
-
140 
-
141  if (!hwloc_topology_is_thissystem(topology)) {
-
142  errno = EINVAL;
-
143  return -1;
-
144  }
-
145 
-
146  if (hwloc_opencl_get_device_pci_busid(device, &pcidomain, &pcibus, &pcidev, &pcifunc) < 0) {
-
147  hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
-
148  return 0;
-
149  }
-
150 
-
151  sprintf(path, "/sys/bus/pci/devices/%04x:%02x:%02x.%01x/local_cpus", pcidomain, pcibus, pcidev, pcifunc);
-
152  if (hwloc_linux_read_path_as_cpumask(path, set) < 0
-
153  || hwloc_bitmap_iszero(set))
-
154  hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
-
155 #else
-
156  /* Non-Linux systems simply get a full cpuset */
-
157  hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
-
158 #endif
-
159  return 0;
-
160 }
-
161 
-
177 static __hwloc_inline hwloc_obj_t
-
178 hwloc_opencl_get_device_osdev_by_index(hwloc_topology_t topology,
-
179  unsigned platform_index, unsigned device_index)
-
180 {
-
181  unsigned x = (unsigned) -1, y = (unsigned) -1;
-
182  hwloc_obj_t osdev = NULL;
-
183  while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
-
184  if (HWLOC_OBJ_OSDEV_COPROC == osdev->attr->osdev.type
-
185  && osdev->name
-
186  && sscanf(osdev->name, "opencl%ud%u", &x, &y) == 2
-
187  && platform_index == x && device_index == y)
-
188  return osdev;
-
189  }
-
190  return NULL;
-
191 }
-
192 
-
214 static __hwloc_inline hwloc_obj_t
-
215 hwloc_opencl_get_device_osdev(hwloc_topology_t topology __hwloc_attribute_unused,
-
216  cl_device_id device __hwloc_attribute_unused)
-
217 {
-
218  hwloc_obj_t osdev;
-
219  unsigned pcidomain, pcibus, pcidevice, pcifunc;
-
220 
-
221  if (hwloc_opencl_get_device_pci_busid(device, &pcidomain, &pcibus, &pcidevice, &pcifunc) < 0) {
-
222  errno = EINVAL;
-
223  return NULL;
-
224  }
-
225 
-
226  osdev = NULL;
-
227  while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
-
228  hwloc_obj_t pcidev = osdev->parent;
-
229  if (strncmp(osdev->name, "opencl", 6))
-
230  continue;
-
231  if (pcidev
-
232  && pcidev->type == HWLOC_OBJ_PCI_DEVICE
-
233  && pcidev->attr->pcidev.domain == pcidomain
-
234  && pcidev->attr->pcidev.bus == pcibus
-
235  && pcidev->attr->pcidev.dev == pcidevice
-
236  && pcidev->attr->pcidev.func == pcifunc)
-
237  return osdev;
-
238  /* if PCI are filtered out, we need a info attr to match on */
-
239  }
-
240 
-
241  return NULL;
-
242 }
-
243 
-
247 #ifdef __cplusplus
-
248 } /* extern "C" */
-
249 #endif
-
250 
-
251 
-
252 #endif /* HWLOC_OPENCL_H */
-
hwloc_cpuset_t
hwloc_bitmap_t hwloc_cpuset_t
A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
Definition: hwloc.h:140
-
HWLOC_OBJ_OSDEV_COPROC
@ HWLOC_OBJ_OSDEV_COPROC
Operating system co-processor device. For instance "opencl0d0" for a OpenCL device,...
Definition: hwloc.h:353
-
HWLOC_OBJ_PCI_DEVICE
@ HWLOC_OBJ_PCI_DEVICE
PCI device (filtered out by default).
Definition: hwloc.h:269
-
hwloc_topology_t
struct hwloc_topology * hwloc_topology_t
Topology context.
Definition: hwloc.h:692
-
hwloc_topology_is_thissystem
int hwloc_topology_is_thissystem(hwloc_topology_t restrict topology)
Does the topology context come from this system?
-
hwloc_topology_get_complete_cpuset
hwloc_const_cpuset_t hwloc_topology_get_complete_cpuset(hwloc_topology_t topology)
Get complete CPU set.
-
hwloc_get_next_osdev
static hwloc_obj_t hwloc_get_next_osdev(hwloc_topology_t topology, hwloc_obj_t prev)
Get the next OS device in the system.
Definition: helper.h:1191
-
hwloc_bitmap_iszero
int hwloc_bitmap_iszero(hwloc_const_bitmap_t bitmap)
Test whether bitmap bitmap is empty.
-
hwloc_bitmap_copy
int hwloc_bitmap_copy(hwloc_bitmap_t dst, hwloc_const_bitmap_t src)
Copy the contents of bitmap src into the already allocated bitmap dst.
-
hwloc_linux_read_path_as_cpumask
int hwloc_linux_read_path_as_cpumask(const char *path, hwloc_bitmap_t set)
Convert a linux kernel cpumask file path into a hwloc bitmap set.
-
hwloc_opencl_get_device_pci_busid
static int hwloc_opencl_get_device_pci_busid(cl_device_id device, unsigned *domain, unsigned *bus, unsigned *dev, unsigned *func)
Return the domain, bus and device IDs of the OpenCL device device.
Definition: opencl.h:74
-
hwloc_opencl_get_device_cpuset
static int hwloc_opencl_get_device_cpuset(hwloc_topology_t topology, cl_device_id device, hwloc_cpuset_t set)
Get the CPU set of processors that are physically close to OpenCL device device.
Definition: opencl.h:131
-
hwloc_opencl_get_device_osdev
static hwloc_obj_t hwloc_opencl_get_device_osdev(hwloc_topology_t topology, cl_device_id device)
Get the hwloc OS device object corresponding to OpenCL device deviceX.
Definition: opencl.h:215
-
hwloc_opencl_get_device_osdev_by_index
static hwloc_obj_t hwloc_opencl_get_device_osdev_by_index(hwloc_topology_t topology, unsigned platform_index, unsigned device_index)
Get the hwloc OS device object corresponding to the OpenCL device for the given indexes.
Definition: opencl.h:178
-
hwloc_obj
Structure of a topology object.
Definition: hwloc.h:396
-
hwloc_obj::name
char * name
Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name str...
Definition: hwloc.h:408
-
hwloc_obj::type
hwloc_obj_type_t type
Type of object.
Definition: hwloc.h:398
-
hwloc_obj::attr
union hwloc_obj_attr_u * attr
Object type-specific Attributes, may be NULL if no attribute value was found.
Definition: hwloc.h:415
-
hwloc_obj::parent
struct hwloc_obj * parent
Parent, NULL if root (Machine object)
Definition: hwloc.h:446
-
hwloc_obj_attr_u::pcidev
struct hwloc_obj_attr_u::hwloc_pcidev_attr_s pcidev
-
hwloc_obj_attr_u::osdev
struct hwloc_obj_attr_u::hwloc_osdev_attr_s osdev
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::dev
unsigned char dev
Definition: hwloc.h:639
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::func
unsigned char func
Definition: hwloc.h:639
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::domain
unsigned short domain
Definition: hwloc.h:635
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::bus
unsigned char bus
Definition: hwloc.h:639
-
hwloc_obj_attr_u::hwloc_osdev_attr_s::type
hwloc_obj_osdev_type_t type
Definition: hwloc.h:666
-
hwloc_cl_device_topology_amd
Definition: opencl.h:46
-
hwloc_cl_device_topology_amd::device
cl_char device
Definition: opencl.h:48
-
hwloc_cl_device_topology_amd::pcie
struct hwloc_cl_device_topology_amd::@4 pcie
-
hwloc_cl_device_topology_amd::bus
cl_char bus
Definition: opencl.h:48
-
hwloc_cl_device_topology_amd::function
cl_char function
Definition: opencl.h:48
-
hwloc_cl_device_topology_amd::raw
struct hwloc_cl_device_topology_amd::@3 raw
-
hwloc_cl_device_topology_amd::type
cl_uint type
Definition: opencl.h:47
-
- - - - - - - - -
-
-
cuda.h
-
-
-
1 /*
-
2  * Copyright © 2010-2021 Inria. All rights reserved.
-
3  * Copyright © 2010-2011 Université Bordeaux
-
4  * Copyright © 2011 Cisco Systems, Inc. All rights reserved.
-
5  * See COPYING in top-level directory.
-
6  */
-
7 
-
16 #ifndef HWLOC_CUDA_H
-
17 #define HWLOC_CUDA_H
-
18 
-
19 #include "hwloc.h"
-
20 #include "hwloc/autogen/config.h"
-
21 #include "hwloc/helper.h"
-
22 #ifdef HWLOC_LINUX_SYS
-
23 #include "hwloc/linux.h"
-
24 #endif
-
25 
-
26 #include <cuda.h>
-
27 
-
28 
-
29 #ifdef __cplusplus
-
30 extern "C" {
-
31 #endif
-
32 
-
33 
-
46 static __hwloc_inline int
-
47 hwloc_cuda_get_device_pci_ids(hwloc_topology_t topology __hwloc_attribute_unused,
-
48  CUdevice cudevice, int *domain, int *bus, int *dev)
-
49 {
-
50  CUresult cres;
-
51 
-
52 #if CUDA_VERSION >= 4000
-
53  cres = cuDeviceGetAttribute(domain, CU_DEVICE_ATTRIBUTE_PCI_DOMAIN_ID, cudevice);
-
54  if (cres != CUDA_SUCCESS) {
-
55  errno = ENOSYS;
-
56  return -1;
-
57  }
-
58 #else
-
59  *domain = 0;
-
60 #endif
-
61  cres = cuDeviceGetAttribute(bus, CU_DEVICE_ATTRIBUTE_PCI_BUS_ID, cudevice);
-
62  if (cres != CUDA_SUCCESS) {
-
63  errno = ENOSYS;
-
64  return -1;
-
65  }
-
66  cres = cuDeviceGetAttribute(dev, CU_DEVICE_ATTRIBUTE_PCI_DEVICE_ID, cudevice);
-
67  if (cres != CUDA_SUCCESS) {
-
68  errno = ENOSYS;
-
69  return -1;
-
70  }
-
71 
-
72  return 0;
-
73 }
-
74 
-
91 static __hwloc_inline int
-
92 hwloc_cuda_get_device_cpuset(hwloc_topology_t topology __hwloc_attribute_unused,
-
93  CUdevice cudevice, hwloc_cpuset_t set)
-
94 {
-
95 #ifdef HWLOC_LINUX_SYS
-
96  /* If we're on Linux, use the sysfs mechanism to get the local cpus */
-
97 #define HWLOC_CUDA_DEVICE_SYSFS_PATH_MAX 128
-
98  char path[HWLOC_CUDA_DEVICE_SYSFS_PATH_MAX];
-
99  int domainid, busid, deviceid;
-
100 
-
101  if (hwloc_cuda_get_device_pci_ids(topology, cudevice, &domainid, &busid, &deviceid))
-
102  return -1;
-
103 
-
104  if (!hwloc_topology_is_thissystem(topology)) {
-
105  errno = EINVAL;
-
106  return -1;
-
107  }
-
108 
-
109  sprintf(path, "/sys/bus/pci/devices/%04x:%02x:%02x.0/local_cpus", domainid, busid, deviceid);
-
110  if (hwloc_linux_read_path_as_cpumask(path, set) < 0
-
111  || hwloc_bitmap_iszero(set))
-
112  hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
-
113 #else
-
114  /* Non-Linux systems simply get a full cpuset */
-
115  hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
-
116 #endif
-
117  return 0;
-
118 }
-
119 
-
130 static __hwloc_inline hwloc_obj_t
-
131 hwloc_cuda_get_device_pcidev(hwloc_topology_t topology, CUdevice cudevice)
-
132 {
-
133  int domain, bus, dev;
-
134 
-
135  if (hwloc_cuda_get_device_pci_ids(topology, cudevice, &domain, &bus, &dev))
-
136  return NULL;
-
137 
-
138  return hwloc_get_pcidev_by_busid(topology, domain, bus, dev, 0);
-
139 }
-
140 
-
156 static __hwloc_inline hwloc_obj_t
-
157 hwloc_cuda_get_device_osdev(hwloc_topology_t topology, CUdevice cudevice)
-
158 {
-
159  hwloc_obj_t osdev = NULL;
-
160  int domain, bus, dev;
-
161 
-
162  if (hwloc_cuda_get_device_pci_ids(topology, cudevice, &domain, &bus, &dev))
-
163  return NULL;
-
164 
-
165  osdev = NULL;
-
166  while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
-
167  hwloc_obj_t pcidev = osdev->parent;
-
168  if (strncmp(osdev->name, "cuda", 4))
-
169  continue;
-
170  if (pcidev
-
171  && pcidev->type == HWLOC_OBJ_PCI_DEVICE
-
172  && (int) pcidev->attr->pcidev.domain == domain
-
173  && (int) pcidev->attr->pcidev.bus == bus
-
174  && (int) pcidev->attr->pcidev.dev == dev
-
175  && pcidev->attr->pcidev.func == 0)
-
176  return osdev;
-
177  /* if PCI are filtered out, we need a info attr to match on */
-
178  }
-
179 
-
180  return NULL;
-
181 }
-
182 
-
198 static __hwloc_inline hwloc_obj_t
-
199 hwloc_cuda_get_device_osdev_by_index(hwloc_topology_t topology, unsigned idx)
-
200 {
-
201  hwloc_obj_t osdev = NULL;
-
202  while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
-
203  if (HWLOC_OBJ_OSDEV_COPROC == osdev->attr->osdev.type
-
204  && osdev->name
-
205  && !strncmp("cuda", osdev->name, 4)
-
206  && atoi(osdev->name + 4) == (int) idx)
-
207  return osdev;
-
208  }
-
209  return NULL;
-
210 }
-
211 
-
215 #ifdef __cplusplus
-
216 } /* extern "C" */
-
217 #endif
-
218 
-
219 
-
220 #endif /* HWLOC_CUDA_H */
-
hwloc_cpuset_t
hwloc_bitmap_t hwloc_cpuset_t
A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
Definition: hwloc.h:140
-
HWLOC_OBJ_OSDEV_COPROC
@ HWLOC_OBJ_OSDEV_COPROC
Operating system co-processor device. For instance "opencl0d0" for a OpenCL device,...
Definition: hwloc.h:353
-
HWLOC_OBJ_PCI_DEVICE
@ HWLOC_OBJ_PCI_DEVICE
PCI device (filtered out by default).
Definition: hwloc.h:269
-
hwloc_topology_t
struct hwloc_topology * hwloc_topology_t
Topology context.
Definition: hwloc.h:692
-
hwloc_topology_is_thissystem
int hwloc_topology_is_thissystem(hwloc_topology_t restrict topology)
Does the topology context come from this system?
-
hwloc_topology_get_complete_cpuset
hwloc_const_cpuset_t hwloc_topology_get_complete_cpuset(hwloc_topology_t topology)
Get complete CPU set.
-
hwloc_get_next_osdev
static hwloc_obj_t hwloc_get_next_osdev(hwloc_topology_t topology, hwloc_obj_t prev)
Get the next OS device in the system.
Definition: helper.h:1191
-
hwloc_get_pcidev_by_busid
static hwloc_obj_t hwloc_get_pcidev_by_busid(hwloc_topology_t topology, unsigned domain, unsigned bus, unsigned dev, unsigned func)
Find the PCI device object matching the PCI bus id given domain, bus device and function PCI bus id.
Definition: helper.h:1154
-
hwloc_bitmap_iszero
int hwloc_bitmap_iszero(hwloc_const_bitmap_t bitmap)
Test whether bitmap bitmap is empty.
-
hwloc_bitmap_copy
int hwloc_bitmap_copy(hwloc_bitmap_t dst, hwloc_const_bitmap_t src)
Copy the contents of bitmap src into the already allocated bitmap dst.
-
hwloc_linux_read_path_as_cpumask
int hwloc_linux_read_path_as_cpumask(const char *path, hwloc_bitmap_t set)
Convert a linux kernel cpumask file path into a hwloc bitmap set.
-
hwloc_cuda_get_device_pci_ids
static int hwloc_cuda_get_device_pci_ids(hwloc_topology_t topology, CUdevice cudevice, int *domain, int *bus, int *dev)
Return the domain, bus and device IDs of the CUDA device cudevice.
Definition: cuda.h:47
-
hwloc_cuda_get_device_pcidev
static hwloc_obj_t hwloc_cuda_get_device_pcidev(hwloc_topology_t topology, CUdevice cudevice)
Get the hwloc PCI device object corresponding to the CUDA device cudevice.
Definition: cuda.h:131
-
hwloc_cuda_get_device_osdev_by_index
static hwloc_obj_t hwloc_cuda_get_device_osdev_by_index(hwloc_topology_t topology, unsigned idx)
Get the hwloc OS device object corresponding to the CUDA device whose index is idx.
Definition: cuda.h:199
-
hwloc_cuda_get_device_osdev
static hwloc_obj_t hwloc_cuda_get_device_osdev(hwloc_topology_t topology, CUdevice cudevice)
Get the hwloc OS device object corresponding to CUDA device cudevice.
Definition: cuda.h:157
-
hwloc_cuda_get_device_cpuset
static int hwloc_cuda_get_device_cpuset(hwloc_topology_t topology, CUdevice cudevice, hwloc_cpuset_t set)
Get the CPU set of processors that are physically close to device cudevice.
Definition: cuda.h:92
-
hwloc_obj
Structure of a topology object.
Definition: hwloc.h:396
-
hwloc_obj::name
char * name
Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name str...
Definition: hwloc.h:408
-
hwloc_obj::type
hwloc_obj_type_t type
Type of object.
Definition: hwloc.h:398
-
hwloc_obj::attr
union hwloc_obj_attr_u * attr
Object type-specific Attributes, may be NULL if no attribute value was found.
Definition: hwloc.h:415
-
hwloc_obj::parent
struct hwloc_obj * parent
Parent, NULL if root (Machine object)
Definition: hwloc.h:446
-
hwloc_obj_attr_u::pcidev
struct hwloc_obj_attr_u::hwloc_pcidev_attr_s pcidev
-
hwloc_obj_attr_u::osdev
struct hwloc_obj_attr_u::hwloc_osdev_attr_s osdev
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::dev
unsigned char dev
Definition: hwloc.h:639
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::func
unsigned char func
Definition: hwloc.h:639
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::domain
unsigned short domain
Definition: hwloc.h:635
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::bus
unsigned char bus
Definition: hwloc.h:639
-
hwloc_obj_attr_u::hwloc_osdev_attr_s::type
hwloc_obj_osdev_type_t type
Definition: hwloc.h:666
-
- - - - - - - - -
-
-
cudart.h
-
-
-
1 /*
-
2  * Copyright © 2010-2021 Inria. All rights reserved.
-
3  * Copyright © 2010-2011 Université Bordeaux
-
4  * Copyright © 2011 Cisco Systems, Inc. All rights reserved.
-
5  * See COPYING in top-level directory.
-
6  */
-
7 
-
16 #ifndef HWLOC_CUDART_H
-
17 #define HWLOC_CUDART_H
-
18 
-
19 #include "hwloc.h"
-
20 #include "hwloc/autogen/config.h"
-
21 #include "hwloc/helper.h"
-
22 #ifdef HWLOC_LINUX_SYS
-
23 #include "hwloc/linux.h"
-
24 #endif
-
25 
-
26 #include <cuda.h> /* for CUDA_VERSION */
-
27 #include <cuda_runtime_api.h>
-
28 
-
29 
-
30 #ifdef __cplusplus
-
31 extern "C" {
-
32 #endif
-
33 
-
34 
-
47 static __hwloc_inline int
-
48 hwloc_cudart_get_device_pci_ids(hwloc_topology_t topology __hwloc_attribute_unused,
-
49  int idx, int *domain, int *bus, int *dev)
-
50 {
-
51  cudaError_t cerr;
-
52  struct cudaDeviceProp prop;
-
53 
-
54  cerr = cudaGetDeviceProperties(&prop, idx);
-
55  if (cerr) {
-
56  errno = ENOSYS;
-
57  return -1;
-
58  }
-
59 
-
60 #if CUDA_VERSION >= 4000
-
61  *domain = prop.pciDomainID;
-
62 #else
-
63  *domain = 0;
-
64 #endif
-
65 
-
66  *bus = prop.pciBusID;
-
67  *dev = prop.pciDeviceID;
-
68 
-
69  return 0;
-
70 }
-
71 
-
88 static __hwloc_inline int
-
89 hwloc_cudart_get_device_cpuset(hwloc_topology_t topology __hwloc_attribute_unused,
-
90  int idx, hwloc_cpuset_t set)
-
91 {
-
92 #ifdef HWLOC_LINUX_SYS
-
93  /* If we're on Linux, use the sysfs mechanism to get the local cpus */
-
94 #define HWLOC_CUDART_DEVICE_SYSFS_PATH_MAX 128
-
95  char path[HWLOC_CUDART_DEVICE_SYSFS_PATH_MAX];
-
96  int domain, bus, dev;
-
97 
-
98  if (hwloc_cudart_get_device_pci_ids(topology, idx, &domain, &bus, &dev))
-
99  return -1;
-
100 
-
101  if (!hwloc_topology_is_thissystem(topology)) {
-
102  errno = EINVAL;
-
103  return -1;
-
104  }
-
105 
-
106  sprintf(path, "/sys/bus/pci/devices/%04x:%02x:%02x.0/local_cpus", (unsigned) domain, (unsigned) bus, (unsigned) dev);
-
107  if (hwloc_linux_read_path_as_cpumask(path, set) < 0
-
108  || hwloc_bitmap_iszero(set))
-
109  hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
-
110 #else
-
111  /* Non-Linux systems simply get a full cpuset */
-
112  hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
-
113 #endif
-
114  return 0;
-
115 }
-
116 
-
127 static __hwloc_inline hwloc_obj_t
-
128 hwloc_cudart_get_device_pcidev(hwloc_topology_t topology, int idx)
-
129 {
-
130  int domain, bus, dev;
-
131 
-
132  if (hwloc_cudart_get_device_pci_ids(topology, idx, &domain, &bus, &dev))
-
133  return NULL;
-
134 
-
135  return hwloc_get_pcidev_by_busid(topology, domain, bus, dev, 0);
-
136 }
-
137 
-
155 static __hwloc_inline hwloc_obj_t
-
156 hwloc_cudart_get_device_osdev_by_index(hwloc_topology_t topology, unsigned idx)
-
157 {
-
158  hwloc_obj_t osdev = NULL;
-
159  while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
-
160  if (HWLOC_OBJ_OSDEV_COPROC == osdev->attr->osdev.type
-
161  && osdev->name
-
162  && !strncmp("cuda", osdev->name, 4)
-
163  && atoi(osdev->name + 4) == (int) idx)
-
164  return osdev;
-
165  }
-
166  return NULL;
-
167 }
-
168 
-
172 #ifdef __cplusplus
-
173 } /* extern "C" */
-
174 #endif
-
175 
-
176 
-
177 #endif /* HWLOC_CUDART_H */
-
hwloc_cpuset_t
hwloc_bitmap_t hwloc_cpuset_t
A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
Definition: hwloc.h:140
-
HWLOC_OBJ_OSDEV_COPROC
@ HWLOC_OBJ_OSDEV_COPROC
Operating system co-processor device. For instance "opencl0d0" for a OpenCL device,...
Definition: hwloc.h:353
-
hwloc_topology_t
struct hwloc_topology * hwloc_topology_t
Topology context.
Definition: hwloc.h:692
-
hwloc_topology_is_thissystem
int hwloc_topology_is_thissystem(hwloc_topology_t restrict topology)
Does the topology context come from this system?
-
hwloc_topology_get_complete_cpuset
hwloc_const_cpuset_t hwloc_topology_get_complete_cpuset(hwloc_topology_t topology)
Get complete CPU set.
-
hwloc_get_next_osdev
static hwloc_obj_t hwloc_get_next_osdev(hwloc_topology_t topology, hwloc_obj_t prev)
Get the next OS device in the system.
Definition: helper.h:1191
-
hwloc_get_pcidev_by_busid
static hwloc_obj_t hwloc_get_pcidev_by_busid(hwloc_topology_t topology, unsigned domain, unsigned bus, unsigned dev, unsigned func)
Find the PCI device object matching the PCI bus id given domain, bus device and function PCI bus id.
Definition: helper.h:1154
-
hwloc_bitmap_iszero
int hwloc_bitmap_iszero(hwloc_const_bitmap_t bitmap)
Test whether bitmap bitmap is empty.
-
hwloc_bitmap_copy
int hwloc_bitmap_copy(hwloc_bitmap_t dst, hwloc_const_bitmap_t src)
Copy the contents of bitmap src into the already allocated bitmap dst.
-
hwloc_linux_read_path_as_cpumask
int hwloc_linux_read_path_as_cpumask(const char *path, hwloc_bitmap_t set)
Convert a linux kernel cpumask file path into a hwloc bitmap set.
-
hwloc_cudart_get_device_cpuset
static int hwloc_cudart_get_device_cpuset(hwloc_topology_t topology, int idx, hwloc_cpuset_t set)
Get the CPU set of processors that are physically close to device idx.
Definition: cudart.h:89
-
hwloc_cudart_get_device_osdev_by_index
static hwloc_obj_t hwloc_cudart_get_device_osdev_by_index(hwloc_topology_t topology, unsigned idx)
Get the hwloc OS device object corresponding to the CUDA device whose index is idx.
Definition: cudart.h:156
-
hwloc_cudart_get_device_pci_ids
static int hwloc_cudart_get_device_pci_ids(hwloc_topology_t topology, int idx, int *domain, int *bus, int *dev)
Return the domain, bus and device IDs of the CUDA device whose index is idx.
Definition: cudart.h:48
-
hwloc_cudart_get_device_pcidev
static hwloc_obj_t hwloc_cudart_get_device_pcidev(hwloc_topology_t topology, int idx)
Get the hwloc PCI device object corresponding to the CUDA device whose index is idx.
Definition: cudart.h:128
-
hwloc_obj
Structure of a topology object.
Definition: hwloc.h:396
-
hwloc_obj::name
char * name
Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name str...
Definition: hwloc.h:408
-
hwloc_obj::attr
union hwloc_obj_attr_u * attr
Object type-specific Attributes, may be NULL if no attribute value was found.
Definition: hwloc.h:415
-
hwloc_obj_attr_u::osdev
struct hwloc_obj_attr_u::hwloc_osdev_attr_s osdev
-
hwloc_obj_attr_u::hwloc_osdev_attr_s::type
hwloc_obj_osdev_type_t type
Definition: hwloc.h:666
-
- - - - - - - - -
-
-
nvml.h
-
-
-
1 /*
-
2  * Copyright © 2012-2021 Inria. All rights reserved.
-
3  * See COPYING in top-level directory.
-
4  */
-
5 
-
13 #ifndef HWLOC_NVML_H
-
14 #define HWLOC_NVML_H
-
15 
-
16 #include "hwloc.h"
-
17 #include "hwloc/autogen/config.h"
-
18 #include "hwloc/helper.h"
-
19 #ifdef HWLOC_LINUX_SYS
-
20 #include "hwloc/linux.h"
-
21 #endif
-
22 
-
23 #include <nvml.h>
-
24 
-
25 
-
26 #ifdef __cplusplus
-
27 extern "C" {
-
28 #endif
-
29 
-
30 
-
55 static __hwloc_inline int
-
56 hwloc_nvml_get_device_cpuset(hwloc_topology_t topology __hwloc_attribute_unused,
-
57  nvmlDevice_t device, hwloc_cpuset_t set)
-
58 {
-
59 #ifdef HWLOC_LINUX_SYS
-
60  /* If we're on Linux, use the sysfs mechanism to get the local cpus */
-
61 #define HWLOC_NVML_DEVICE_SYSFS_PATH_MAX 128
-
62  char path[HWLOC_NVML_DEVICE_SYSFS_PATH_MAX];
-
63  nvmlReturn_t nvres;
-
64  nvmlPciInfo_t pci;
-
65 
-
66  if (!hwloc_topology_is_thissystem(topology)) {
-
67  errno = EINVAL;
-
68  return -1;
-
69  }
-
70 
-
71  nvres = nvmlDeviceGetPciInfo(device, &pci);
-
72  if (NVML_SUCCESS != nvres) {
-
73  errno = EINVAL;
-
74  return -1;
-
75  }
-
76 
-
77  sprintf(path, "/sys/bus/pci/devices/%04x:%02x:%02x.0/local_cpus", pci.domain, pci.bus, pci.device);
-
78  if (hwloc_linux_read_path_as_cpumask(path, set) < 0
-
79  || hwloc_bitmap_iszero(set))
-
80  hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
-
81 #else
-
82  /* Non-Linux systems simply get a full cpuset */
-
83  hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
-
84 #endif
-
85  return 0;
-
86 }
-
87 
-
101 static __hwloc_inline hwloc_obj_t
-
102 hwloc_nvml_get_device_osdev_by_index(hwloc_topology_t topology, unsigned idx)
-
103 {
-
104  hwloc_obj_t osdev = NULL;
-
105  while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
-
106  if (HWLOC_OBJ_OSDEV_GPU == osdev->attr->osdev.type
-
107  && osdev->name
-
108  && !strncmp("nvml", osdev->name, 4)
-
109  && atoi(osdev->name + 4) == (int) idx)
-
110  return osdev;
-
111  }
-
112  return NULL;
-
113 }
-
114 
-
128 static __hwloc_inline hwloc_obj_t
-
129 hwloc_nvml_get_device_osdev(hwloc_topology_t topology, nvmlDevice_t device)
-
130 {
-
131  hwloc_obj_t osdev;
-
132  nvmlReturn_t nvres;
-
133  nvmlPciInfo_t pci;
-
134  char uuid[64];
-
135 
-
136  if (!hwloc_topology_is_thissystem(topology)) {
-
137  errno = EINVAL;
-
138  return NULL;
-
139  }
-
140 
-
141  nvres = nvmlDeviceGetPciInfo(device, &pci);
-
142  if (NVML_SUCCESS != nvres)
-
143  return NULL;
-
144 
-
145  nvres = nvmlDeviceGetUUID(device, uuid, sizeof(uuid));
-
146  if (NVML_SUCCESS != nvres)
-
147  uuid[0] = '\0';
-
148 
-
149  osdev = NULL;
-
150  while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
-
151  hwloc_obj_t pcidev = osdev->parent;
-
152  const char *info;
-
153 
-
154  if (strncmp(osdev->name, "nvml", 4))
-
155  continue;
-
156 
-
157  if (pcidev
-
158  && pcidev->type == HWLOC_OBJ_PCI_DEVICE
-
159  && pcidev->attr->pcidev.domain == pci.domain
-
160  && pcidev->attr->pcidev.bus == pci.bus
-
161  && pcidev->attr->pcidev.dev == pci.device
-
162  && pcidev->attr->pcidev.func == 0)
-
163  return osdev;
-
164 
-
165  info = hwloc_obj_get_info_by_name(osdev, "NVIDIAUUID");
-
166  if (info && !strcmp(info, uuid))
-
167  return osdev;
-
168  }
-
169 
-
170  return NULL;
-
171 }
-
172 
-
176 #ifdef __cplusplus
-
177 } /* extern "C" */
-
178 #endif
-
179 
-
180 
-
181 #endif /* HWLOC_NVML_H */
-
hwloc_cpuset_t
hwloc_bitmap_t hwloc_cpuset_t
A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
Definition: hwloc.h:140
-
HWLOC_OBJ_OSDEV_GPU
@ HWLOC_OBJ_OSDEV_GPU
Operating system GPU device. For instance ":0.0" for a GL display, "card0" for a Linux DRM device.
Definition: hwloc.h:342
-
HWLOC_OBJ_PCI_DEVICE
@ HWLOC_OBJ_PCI_DEVICE
PCI device (filtered out by default).
Definition: hwloc.h:269
-
hwloc_topology_t
struct hwloc_topology * hwloc_topology_t
Topology context.
Definition: hwloc.h:692
-
hwloc_obj_get_info_by_name
static const char * hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name)
Search the given key name in object infos and return the corresponding value.
-
hwloc_topology_is_thissystem
int hwloc_topology_is_thissystem(hwloc_topology_t restrict topology)
Does the topology context come from this system?
-
hwloc_topology_get_complete_cpuset
hwloc_const_cpuset_t hwloc_topology_get_complete_cpuset(hwloc_topology_t topology)
Get complete CPU set.
-
hwloc_get_next_osdev
static hwloc_obj_t hwloc_get_next_osdev(hwloc_topology_t topology, hwloc_obj_t prev)
Get the next OS device in the system.
Definition: helper.h:1191
-
hwloc_bitmap_iszero
int hwloc_bitmap_iszero(hwloc_const_bitmap_t bitmap)
Test whether bitmap bitmap is empty.
-
hwloc_bitmap_copy
int hwloc_bitmap_copy(hwloc_bitmap_t dst, hwloc_const_bitmap_t src)
Copy the contents of bitmap src into the already allocated bitmap dst.
-
hwloc_linux_read_path_as_cpumask
int hwloc_linux_read_path_as_cpumask(const char *path, hwloc_bitmap_t set)
Convert a linux kernel cpumask file path into a hwloc bitmap set.
-
hwloc_nvml_get_device_cpuset
static int hwloc_nvml_get_device_cpuset(hwloc_topology_t topology, nvmlDevice_t device, hwloc_cpuset_t set)
Get the CPU set of processors that are physically close to NVML device device.
Definition: nvml.h:56
-
hwloc_nvml_get_device_osdev_by_index
static hwloc_obj_t hwloc_nvml_get_device_osdev_by_index(hwloc_topology_t topology, unsigned idx)
Get the hwloc OS device object corresponding to the NVML device whose index is idx.
Definition: nvml.h:102
-
hwloc_nvml_get_device_osdev
static hwloc_obj_t hwloc_nvml_get_device_osdev(hwloc_topology_t topology, nvmlDevice_t device)
Get the hwloc OS device object corresponding to NVML device device.
Definition: nvml.h:129
-
hwloc_obj
Structure of a topology object.
Definition: hwloc.h:396
-
hwloc_obj::name
char * name
Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name str...
Definition: hwloc.h:408
-
hwloc_obj::type
hwloc_obj_type_t type
Type of object.
Definition: hwloc.h:398
-
hwloc_obj::attr
union hwloc_obj_attr_u * attr
Object type-specific Attributes, may be NULL if no attribute value was found.
Definition: hwloc.h:415
-
hwloc_obj::parent
struct hwloc_obj * parent
Parent, NULL if root (Machine object)
Definition: hwloc.h:446
-
hwloc_obj_attr_u::pcidev
struct hwloc_obj_attr_u::hwloc_pcidev_attr_s pcidev
-
hwloc_obj_attr_u::osdev
struct hwloc_obj_attr_u::hwloc_osdev_attr_s osdev
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::dev
unsigned char dev
Definition: hwloc.h:639
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::func
unsigned char func
Definition: hwloc.h:639
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::domain
unsigned short domain
Definition: hwloc.h:635
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::bus
unsigned char bus
Definition: hwloc.h:639
-
hwloc_obj_attr_u::hwloc_osdev_attr_s::type
hwloc_obj_osdev_type_t type
Definition: hwloc.h:666
-
- - - - - - - - -
-
-
rsmi.h
-
-
-
1 /*
-
2  * Copyright © 2012-2021 Inria. All rights reserved.
-
3  * Copyright (c) 2020, Advanced Micro Devices, Inc. All rights reserved.
-
4  * Written by Advanced Micro Devices,
-
5  * See COPYING in top-level directory.
-
6  */
-
7 
-
15 #ifndef HWLOC_RSMI_H
-
16 #define HWLOC_RSMI_H
-
17 
-
18 #include "hwloc.h"
-
19 #include "hwloc/autogen/config.h"
-
20 #include "hwloc/helper.h"
-
21 #ifdef HWLOC_LINUX_SYS
-
22 #include "hwloc/linux.h"
-
23 #endif
-
24 
-
25 #include <rocm_smi/rocm_smi.h>
-
26 
-
27 
-
28 #ifdef __cplusplus
-
29 extern "C" {
-
30 #endif
-
31 
-
32 
-
59 static __hwloc_inline int
-
60 hwloc_rsmi_get_device_cpuset(hwloc_topology_t topology __hwloc_attribute_unused,
-
61  uint32_t dv_ind, hwloc_cpuset_t set)
-
62 {
-
63 #ifdef HWLOC_LINUX_SYS
-
64  /* If we're on Linux, use the sysfs mechanism to get the local cpus */
-
65 #define HWLOC_RSMI_DEVICE_SYSFS_PATH_MAX 128
-
66  char path[HWLOC_RSMI_DEVICE_SYSFS_PATH_MAX];
-
67  rsmi_status_t ret;
-
68  uint64_t bdfid = 0;
-
69  unsigned domain, device, bus;
-
70 
-
71  if (!hwloc_topology_is_thissystem(topology)) {
-
72  errno = EINVAL;
-
73  return -1;
-
74  }
-
75 
-
76  ret = rsmi_dev_pci_id_get(dv_ind, &bdfid);
-
77  if (RSMI_STATUS_SUCCESS != ret) {
-
78  errno = EINVAL;
-
79  return -1;
-
80  }
-
81  domain = (bdfid>>32) & 0xffffffff;
-
82  bus = ((bdfid & 0xffff)>>8) & 0xff;
-
83  device = ((bdfid & 0xff)>>3) & 0x1f;
-
84 
-
85  sprintf(path, "/sys/bus/pci/devices/%04x:%02x:%02x.0/local_cpus", domain, bus, device);
-
86  if (hwloc_linux_read_path_as_cpumask(path, set) < 0
-
87  || hwloc_bitmap_iszero(set))
-
88  hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
-
89 #else
-
90  /* Non-Linux systems simply get a full cpuset */
-
91  hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
-
92 #endif
-
93  return 0;
-
94 }
-
95 
-
111 static __hwloc_inline hwloc_obj_t
-
112 hwloc_rsmi_get_device_osdev_by_index(hwloc_topology_t topology, uint32_t dv_ind)
-
113 {
-
114  hwloc_obj_t osdev = NULL;
-
115  while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
-
116  if (HWLOC_OBJ_OSDEV_GPU == osdev->attr->osdev.type
-
117  && osdev->name
-
118  && !strncmp("rsmi", osdev->name, 4)
-
119  && atoi(osdev->name + 4) == (int) dv_ind)
-
120  return osdev;
-
121  }
-
122  return NULL;
-
123 }
-
124 
-
140 static __hwloc_inline hwloc_obj_t
-
141 hwloc_rsmi_get_device_osdev(hwloc_topology_t topology, uint32_t dv_ind)
-
142 {
-
143  hwloc_obj_t osdev;
-
144  rsmi_status_t ret;
-
145  uint64_t bdfid = 0;
-
146  unsigned domain, device, bus, func;
-
147  uint64_t id;
-
148  char uuid[64];
-
149 
-
150  if (!hwloc_topology_is_thissystem(topology)) {
-
151  errno = EINVAL;
-
152  return NULL;
-
153  }
-
154 
-
155  ret = rsmi_dev_pci_id_get(dv_ind, &bdfid);
-
156  if (RSMI_STATUS_SUCCESS != ret) {
-
157  errno = EINVAL;
-
158  return NULL;
-
159  }
-
160  domain = (bdfid>>32) & 0xffffffff;
-
161  bus = ((bdfid & 0xffff)>>8) & 0xff;
-
162  device = ((bdfid & 0xff)>>3) & 0x1f;
-
163  func = bdfid & 0x7;
-
164 
-
165  ret = rsmi_dev_unique_id_get(dv_ind, &id);
-
166  if (RSMI_STATUS_SUCCESS != ret)
-
167  uuid[0] = '\0';
-
168  else
-
169  sprintf(uuid, "%lx", id);
-
170 
-
171  osdev = NULL;
-
172  while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
-
173  hwloc_obj_t pcidev = osdev->parent;
-
174  const char *info;
-
175 
-
176  if (strncmp(osdev->name, "rsmi", 4))
-
177  continue;
-
178 
-
179  if (pcidev
-
180  && pcidev->type == HWLOC_OBJ_PCI_DEVICE
-
181  && pcidev->attr->pcidev.domain == domain
-
182  && pcidev->attr->pcidev.bus == bus
-
183  && pcidev->attr->pcidev.dev == device
-
184  && pcidev->attr->pcidev.func == func)
-
185  return osdev;
-
186 
-
187  info = hwloc_obj_get_info_by_name(osdev, "AMDUUID");
-
188  if (info && !strcmp(info, uuid))
-
189  return osdev;
-
190  }
-
191 
-
192  return NULL;
-
193 }
-
194 
-
198 #ifdef __cplusplus
-
199 } /* extern "C" */
-
200 #endif
-
201 
-
202 
-
203 #endif /* HWLOC_RSMI_H */
-
hwloc_cpuset_t
hwloc_bitmap_t hwloc_cpuset_t
A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
Definition: hwloc.h:140
-
HWLOC_OBJ_OSDEV_GPU
@ HWLOC_OBJ_OSDEV_GPU
Operating system GPU device. For instance ":0.0" for a GL display, "card0" for a Linux DRM device.
Definition: hwloc.h:342
-
HWLOC_OBJ_PCI_DEVICE
@ HWLOC_OBJ_PCI_DEVICE
PCI device (filtered out by default).
Definition: hwloc.h:269
-
hwloc_topology_t
struct hwloc_topology * hwloc_topology_t
Topology context.
Definition: hwloc.h:692
-
hwloc_obj_get_info_by_name
static const char * hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name)
Search the given key name in object infos and return the corresponding value.
-
hwloc_topology_is_thissystem
int hwloc_topology_is_thissystem(hwloc_topology_t restrict topology)
Does the topology context come from this system?
-
hwloc_topology_get_complete_cpuset
hwloc_const_cpuset_t hwloc_topology_get_complete_cpuset(hwloc_topology_t topology)
Get complete CPU set.
-
hwloc_get_next_osdev
static hwloc_obj_t hwloc_get_next_osdev(hwloc_topology_t topology, hwloc_obj_t prev)
Get the next OS device in the system.
Definition: helper.h:1191
-
hwloc_bitmap_iszero
int hwloc_bitmap_iszero(hwloc_const_bitmap_t bitmap)
Test whether bitmap bitmap is empty.
-
hwloc_bitmap_copy
int hwloc_bitmap_copy(hwloc_bitmap_t dst, hwloc_const_bitmap_t src)
Copy the contents of bitmap src into the already allocated bitmap dst.
-
hwloc_linux_read_path_as_cpumask
int hwloc_linux_read_path_as_cpumask(const char *path, hwloc_bitmap_t set)
Convert a linux kernel cpumask file path into a hwloc bitmap set.
-
hwloc_rsmi_get_device_osdev_by_index
static hwloc_obj_t hwloc_rsmi_get_device_osdev_by_index(hwloc_topology_t topology, uint32_t dv_ind)
Get the hwloc OS device object corresponding to the AMD GPU device whose index is dv_ind.
Definition: rsmi.h:112
-
hwloc_rsmi_get_device_osdev
static hwloc_obj_t hwloc_rsmi_get_device_osdev(hwloc_topology_t topology, uint32_t dv_ind)
Get the hwloc OS device object corresponding to AMD GPU device, whose index is dv_ind.
Definition: rsmi.h:141
-
hwloc_rsmi_get_device_cpuset
static int hwloc_rsmi_get_device_cpuset(hwloc_topology_t topology, uint32_t dv_ind, hwloc_cpuset_t set)
Get the CPU set of logical processors that are physically close to AMD GPU device whose index is dv_i...
Definition: rsmi.h:60
-
hwloc_obj
Structure of a topology object.
Definition: hwloc.h:396
-
hwloc_obj::name
char * name
Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name str...
Definition: hwloc.h:408
-
hwloc_obj::type
hwloc_obj_type_t type
Type of object.
Definition: hwloc.h:398
-
hwloc_obj::attr
union hwloc_obj_attr_u * attr
Object type-specific Attributes, may be NULL if no attribute value was found.
Definition: hwloc.h:415
-
hwloc_obj::parent
struct hwloc_obj * parent
Parent, NULL if root (Machine object)
Definition: hwloc.h:446
-
hwloc_obj_attr_u::pcidev
struct hwloc_obj_attr_u::hwloc_pcidev_attr_s pcidev
-
hwloc_obj_attr_u::osdev
struct hwloc_obj_attr_u::hwloc_osdev_attr_s osdev
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::dev
unsigned char dev
Definition: hwloc.h:639
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::func
unsigned char func
Definition: hwloc.h:639
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::domain
unsigned short domain
Definition: hwloc.h:635
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::bus
unsigned char bus
Definition: hwloc.h:639
-
hwloc_obj_attr_u::hwloc_osdev_attr_s::type
hwloc_obj_osdev_type_t type
Definition: hwloc.h:666
-
- - - - - - - - -
-
-
levelzero.h
-
-
-
1 /*
-
2  * Copyright © 2021 Inria. All rights reserved.
-
3  * See COPYING in top-level directory.
-
4  */
-
5 
-
13 #ifndef HWLOC_LEVELZERO_H
-
14 #define HWLOC_LEVELZERO_H
-
15 
-
16 #include "hwloc.h"
-
17 #include "hwloc/autogen/config.h"
-
18 #include "hwloc/helper.h"
-
19 #ifdef HWLOC_LINUX_SYS
-
20 #include "hwloc/linux.h"
-
21 #endif
-
22 
-
23 #include <level_zero/ze_api.h>
-
24 #include <level_zero/zes_api.h>
-
25 
-
26 
-
27 #ifdef __cplusplus
-
28 extern "C" {
-
29 #endif
-
30 
-
31 
-
59 static __hwloc_inline int
-
60 hwloc_levelzero_get_device_cpuset(hwloc_topology_t topology __hwloc_attribute_unused,
-
61  ze_device_handle_t device, hwloc_cpuset_t set)
-
62 {
-
63 #ifdef HWLOC_LINUX_SYS
-
64  /* If we're on Linux, use the sysfs mechanism to get the local cpus */
-
65 #define HWLOC_LEVELZERO_DEVICE_SYSFS_PATH_MAX 128
-
66  char path[HWLOC_LEVELZERO_DEVICE_SYSFS_PATH_MAX];
-
67  zes_pci_properties_t pci;
-
68  zes_device_handle_t sdevice = device;
-
69  ze_result_t res;
-
70 
-
71  if (!hwloc_topology_is_thissystem(topology)) {
-
72  errno = EINVAL;
-
73  return -1;
-
74  }
-
75 
-
76  res = zesDevicePciGetProperties(sdevice, &pci);
-
77  if (res != ZE_RESULT_SUCCESS) {
-
78  errno = EINVAL;
-
79  return -1;
-
80  }
-
81 
-
82  sprintf(path, "/sys/bus/pci/devices/%04x:%02x:%02x.%01x/local_cpus",
-
83  pci.address.domain, pci.address.bus, pci.address.device, pci.address.function);
-
84  if (hwloc_linux_read_path_as_cpumask(path, set) < 0
-
85  || hwloc_bitmap_iszero(set))
-
86  hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
-
87 #else
-
88  /* Non-Linux systems simply get a full cpuset */
-
89  hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
-
90 #endif
-
91  return 0;
-
92 }
-
93 
-
108 static __hwloc_inline hwloc_obj_t
-
109 hwloc_levelzero_get_device_osdev(hwloc_topology_t topology, ze_device_handle_t device)
-
110 {
-
111  zes_device_handle_t sdevice = device;
-
112  zes_pci_properties_t pci;
-
113  ze_result_t res;
-
114  hwloc_obj_t osdev;
-
115 
-
116  if (!hwloc_topology_is_thissystem(topology)) {
-
117  errno = EINVAL;
-
118  return NULL;
-
119  }
-
120 
-
121  res = zesDevicePciGetProperties(sdevice, &pci);
-
122  if (res != ZE_RESULT_SUCCESS) {
-
123  /* L0 was likely initialized without sysman, don't bother */
-
124  errno = EINVAL;
-
125  return NULL;
-
126  }
-
127 
-
128  osdev = NULL;
-
129  while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
-
130  hwloc_obj_t pcidev = osdev->parent;
-
131 
-
132  if (strncmp(osdev->name, "ze", 2))
-
133  continue;
-
134 
-
135  if (pcidev
-
136  && pcidev->type == HWLOC_OBJ_PCI_DEVICE
-
137  && pcidev->attr->pcidev.domain == pci.address.domain
-
138  && pcidev->attr->pcidev.bus == pci.address.bus
-
139  && pcidev->attr->pcidev.dev == pci.address.device
-
140  && pcidev->attr->pcidev.func == pci.address.function)
-
141  return osdev;
-
142 
-
143  /* FIXME: when we'll have serialnumber, try it in case PCI is filtered-out */
-
144  }
-
145 
-
146  return NULL;
-
147 }
-
148 
-
152 #ifdef __cplusplus
-
153 } /* extern "C" */
-
154 #endif
-
155 
-
156 
-
157 #endif /* HWLOC_LEVELZERO_H */
-
hwloc_cpuset_t
hwloc_bitmap_t hwloc_cpuset_t
A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
Definition: hwloc.h:140
-
HWLOC_OBJ_PCI_DEVICE
@ HWLOC_OBJ_PCI_DEVICE
PCI device (filtered out by default).
Definition: hwloc.h:269
-
hwloc_topology_t
struct hwloc_topology * hwloc_topology_t
Topology context.
Definition: hwloc.h:692
-
hwloc_topology_is_thissystem
int hwloc_topology_is_thissystem(hwloc_topology_t restrict topology)
Does the topology context come from this system?
-
hwloc_topology_get_complete_cpuset
hwloc_const_cpuset_t hwloc_topology_get_complete_cpuset(hwloc_topology_t topology)
Get complete CPU set.
-
hwloc_get_next_osdev
static hwloc_obj_t hwloc_get_next_osdev(hwloc_topology_t topology, hwloc_obj_t prev)
Get the next OS device in the system.
Definition: helper.h:1191
-
hwloc_bitmap_iszero
int hwloc_bitmap_iszero(hwloc_const_bitmap_t bitmap)
Test whether bitmap bitmap is empty.
-
hwloc_bitmap_copy
int hwloc_bitmap_copy(hwloc_bitmap_t dst, hwloc_const_bitmap_t src)
Copy the contents of bitmap src into the already allocated bitmap dst.
-
hwloc_linux_read_path_as_cpumask
int hwloc_linux_read_path_as_cpumask(const char *path, hwloc_bitmap_t set)
Convert a linux kernel cpumask file path into a hwloc bitmap set.
-
hwloc_levelzero_get_device_cpuset
static int hwloc_levelzero_get_device_cpuset(hwloc_topology_t topology, ze_device_handle_t device, hwloc_cpuset_t set)
Get the CPU set of logical processors that are physically close to the Level Zero device device.
Definition: levelzero.h:60
-
hwloc_levelzero_get_device_osdev
static hwloc_obj_t hwloc_levelzero_get_device_osdev(hwloc_topology_t topology, ze_device_handle_t device)
Get the hwloc OS device object corresponding to Level Zero device device.
Definition: levelzero.h:109
-
hwloc_obj
Structure of a topology object.
Definition: hwloc.h:396
-
hwloc_obj::name
char * name
Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name str...
Definition: hwloc.h:408
-
hwloc_obj::type
hwloc_obj_type_t type
Type of object.
Definition: hwloc.h:398
-
hwloc_obj::attr
union hwloc_obj_attr_u * attr
Object type-specific Attributes, may be NULL if no attribute value was found.
Definition: hwloc.h:415
-
hwloc_obj::parent
struct hwloc_obj * parent
Parent, NULL if root (Machine object)
Definition: hwloc.h:446
-
hwloc_obj_attr_u::pcidev
struct hwloc_obj_attr_u::hwloc_pcidev_attr_s pcidev
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::dev
unsigned char dev
Definition: hwloc.h:639
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::func
unsigned char func
Definition: hwloc.h:639
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::domain
unsigned short domain
Definition: hwloc.h:635
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::bus
unsigned char bus
Definition: hwloc.h:639
-
- - - - - - - - -
-
-
gl.h
-
-
-
1 /*
-
2  * Copyright © 2012 Blue Brain Project, EPFL. All rights reserved.
-
3  * Copyright © 2012-2021 Inria. All rights reserved.
-
4  * See COPYING in top-level directory.
-
5  */
-
6 
-
14 #ifndef HWLOC_GL_H
-
15 #define HWLOC_GL_H
-
16 
-
17 #include "hwloc.h"
-
18 
-
19 #include <stdio.h>
-
20 #include <string.h>
-
21 
-
22 
-
23 #ifdef __cplusplus
-
24 extern "C" {
-
25 #endif
-
26 
-
27 
-
53 static __hwloc_inline hwloc_obj_t
-
54 hwloc_gl_get_display_osdev_by_port_device(hwloc_topology_t topology,
-
55  unsigned port, unsigned device)
-
56 {
-
57  unsigned x = (unsigned) -1, y = (unsigned) -1;
-
58  hwloc_obj_t osdev = NULL;
-
59  while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
-
60  if (HWLOC_OBJ_OSDEV_GPU == osdev->attr->osdev.type
-
61  && osdev->name
-
62  && sscanf(osdev->name, ":%u.%u", &x, &y) == 2
-
63  && port == x && device == y)
-
64  return osdev;
-
65  }
-
66  errno = EINVAL;
-
67  return NULL;
-
68 }
-
69 
-
84 static __hwloc_inline hwloc_obj_t
-
85 hwloc_gl_get_display_osdev_by_name(hwloc_topology_t topology,
-
86  const char *name)
-
87 {
-
88  hwloc_obj_t osdev = NULL;
-
89  while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
-
90  if (HWLOC_OBJ_OSDEV_GPU == osdev->attr->osdev.type
-
91  && osdev->name
-
92  && !strcmp(name, osdev->name))
-
93  return osdev;
-
94  }
-
95  errno = EINVAL;
-
96  return NULL;
-
97 }
-
98 
-
111 static __hwloc_inline int
-
112 hwloc_gl_get_display_by_osdev(hwloc_topology_t topology __hwloc_attribute_unused,
-
113  hwloc_obj_t osdev,
-
114  unsigned *port, unsigned *device)
-
115 {
-
116  unsigned x = -1, y = -1;
-
117  if (HWLOC_OBJ_OSDEV_GPU == osdev->attr->osdev.type
-
118  && sscanf(osdev->name, ":%u.%u", &x, &y) == 2) {
-
119  *port = x;
-
120  *device = y;
-
121  return 0;
-
122  }
-
123  errno = EINVAL;
-
124  return -1;
-
125 }
-
126 
-
130 #ifdef __cplusplus
-
131 } /* extern "C" */
-
132 #endif
-
133 
-
134 
-
135 #endif /* HWLOC_GL_H */
-
136 
-
HWLOC_OBJ_OSDEV_GPU
@ HWLOC_OBJ_OSDEV_GPU
Operating system GPU device. For instance ":0.0" for a GL display, "card0" for a Linux DRM device.
Definition: hwloc.h:342
-
hwloc_topology_t
struct hwloc_topology * hwloc_topology_t
Topology context.
Definition: hwloc.h:692
-
hwloc_get_next_osdev
static hwloc_obj_t hwloc_get_next_osdev(hwloc_topology_t topology, hwloc_obj_t prev)
Get the next OS device in the system.
Definition: helper.h:1191
-
hwloc_gl_get_display_osdev_by_name
static hwloc_obj_t hwloc_gl_get_display_osdev_by_name(hwloc_topology_t topology, const char *name)
Get the hwloc OS device object corresponding to the OpenGL display given by name.
Definition: gl.h:85
-
hwloc_gl_get_display_osdev_by_port_device
static hwloc_obj_t hwloc_gl_get_display_osdev_by_port_device(hwloc_topology_t topology, unsigned port, unsigned device)
Get the hwloc OS device object corresponding to the OpenGL display given by port and device index.
Definition: gl.h:54
-
hwloc_gl_get_display_by_osdev
static int hwloc_gl_get_display_by_osdev(hwloc_topology_t topology, hwloc_obj_t osdev, unsigned *port, unsigned *device)
Get the OpenGL display port and device corresponding to the given hwloc OS object.
Definition: gl.h:112
-
hwloc_obj
Structure of a topology object.
Definition: hwloc.h:396
-
hwloc_obj::name
char * name
Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name str...
Definition: hwloc.h:408
-
hwloc_obj::attr
union hwloc_obj_attr_u * attr
Object type-specific Attributes, may be NULL if no attribute value was found.
Definition: hwloc.h:415
-
hwloc_obj_attr_u::osdev
struct hwloc_obj_attr_u::hwloc_osdev_attr_s osdev
-
hwloc_obj_attr_u::hwloc_osdev_attr_s::type
hwloc_obj_osdev_type_t type
Definition: hwloc.h:666
-
- - - - - - - - -
-
-
openfabrics-verbs.h
-
-
-
1 /*
-
2  * Copyright © 2009 CNRS
-
3  * Copyright © 2009-2021 Inria. All rights reserved.
-
4  * Copyright © 2009-2010 Université Bordeaux
-
5  * Copyright © 2009-2011 Cisco Systems, Inc. All rights reserved.
-
6  * See COPYING in top-level directory.
-
7  */
-
8 
-
19 #ifndef HWLOC_OPENFABRICS_VERBS_H
-
20 #define HWLOC_OPENFABRICS_VERBS_H
-
21 
-
22 #include "hwloc.h"
-
23 #include "hwloc/autogen/config.h"
-
24 #ifdef HWLOC_LINUX_SYS
-
25 #include "hwloc/linux.h"
-
26 #endif
-
27 
-
28 #include <infiniband/verbs.h>
-
29 
-
30 
-
31 #ifdef __cplusplus
-
32 extern "C" {
-
33 #endif
-
34 
-
35 
-
61 static __hwloc_inline int
-
62 hwloc_ibv_get_device_cpuset(hwloc_topology_t topology __hwloc_attribute_unused,
-
63  struct ibv_device *ibdev, hwloc_cpuset_t set)
-
64 {
-
65 #ifdef HWLOC_LINUX_SYS
-
66  /* If we're on Linux, use the verbs-provided sysfs mechanism to
-
67  get the local cpus */
-
68 #define HWLOC_OPENFABRICS_VERBS_SYSFS_PATH_MAX 128
-
69  char path[HWLOC_OPENFABRICS_VERBS_SYSFS_PATH_MAX];
-
70 
-
71  if (!hwloc_topology_is_thissystem(topology)) {
-
72  errno = EINVAL;
-
73  return -1;
-
74  }
-
75 
-
76  sprintf(path, "/sys/class/infiniband/%s/device/local_cpus",
-
77  ibv_get_device_name(ibdev));
-
78  if (hwloc_linux_read_path_as_cpumask(path, set) < 0
-
79  || hwloc_bitmap_iszero(set))
-
80  hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
-
81 #else
-
82  /* Non-Linux systems simply get a full cpuset */
-
83  hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
-
84 #endif
-
85  return 0;
-
86 }
-
87 
-
105 static __hwloc_inline hwloc_obj_t
-
106 hwloc_ibv_get_device_osdev_by_name(hwloc_topology_t topology,
-
107  const char *ibname)
-
108 {
-
109  hwloc_obj_t osdev = NULL;
-
110  while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
-
111  if (HWLOC_OBJ_OSDEV_OPENFABRICS == osdev->attr->osdev.type
-
112  && osdev->name && !strcmp(ibname, osdev->name))
-
113  return osdev;
-
114  }
-
115  return NULL;
-
116 }
-
117 
-
133 static __hwloc_inline hwloc_obj_t
-
134 hwloc_ibv_get_device_osdev(hwloc_topology_t topology,
-
135  struct ibv_device *ibdev)
-
136 {
-
137  if (!hwloc_topology_is_thissystem(topology)) {
-
138  errno = EINVAL;
-
139  return NULL;
-
140  }
-
141  return hwloc_ibv_get_device_osdev_by_name(topology, ibv_get_device_name(ibdev));
-
142 }
-
143 
-
147 #ifdef __cplusplus
-
148 } /* extern "C" */
-
149 #endif
-
150 
-
151 
-
152 #endif /* HWLOC_OPENFABRICS_VERBS_H */
-
hwloc_cpuset_t
hwloc_bitmap_t hwloc_cpuset_t
A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
Definition: hwloc.h:140
-
HWLOC_OBJ_OSDEV_OPENFABRICS
@ HWLOC_OBJ_OSDEV_OPENFABRICS
Operating system openfabrics device. For instance the "mlx4_0" InfiniBand HCA, "hfi1_0" Omni-Path int...
Definition: hwloc.h:347
-
hwloc_topology_t
struct hwloc_topology * hwloc_topology_t
Topology context.
Definition: hwloc.h:692
-
hwloc_topology_is_thissystem
int hwloc_topology_is_thissystem(hwloc_topology_t restrict topology)
Does the topology context come from this system?
-
hwloc_topology_get_complete_cpuset
hwloc_const_cpuset_t hwloc_topology_get_complete_cpuset(hwloc_topology_t topology)
Get complete CPU set.
-
hwloc_get_next_osdev
static hwloc_obj_t hwloc_get_next_osdev(hwloc_topology_t topology, hwloc_obj_t prev)
Get the next OS device in the system.
Definition: helper.h:1191
-
hwloc_bitmap_iszero
int hwloc_bitmap_iszero(hwloc_const_bitmap_t bitmap)
Test whether bitmap bitmap is empty.
-
hwloc_bitmap_copy
int hwloc_bitmap_copy(hwloc_bitmap_t dst, hwloc_const_bitmap_t src)
Copy the contents of bitmap src into the already allocated bitmap dst.
-
hwloc_linux_read_path_as_cpumask
int hwloc_linux_read_path_as_cpumask(const char *path, hwloc_bitmap_t set)
Convert a linux kernel cpumask file path into a hwloc bitmap set.
-
hwloc_ibv_get_device_osdev_by_name
static hwloc_obj_t hwloc_ibv_get_device_osdev_by_name(hwloc_topology_t topology, const char *ibname)
Get the hwloc OS device object corresponding to the OpenFabrics device named ibname.
Definition: openfabrics-verbs.h:106
-
hwloc_ibv_get_device_cpuset
static int hwloc_ibv_get_device_cpuset(hwloc_topology_t topology, struct ibv_device *ibdev, hwloc_cpuset_t set)
Get the CPU set of processors that are physically close to device ibdev.
Definition: openfabrics-verbs.h:62
-
hwloc_ibv_get_device_osdev
static hwloc_obj_t hwloc_ibv_get_device_osdev(hwloc_topology_t topology, struct ibv_device *ibdev)
Get the hwloc OS device object corresponding to the OpenFabrics device ibdev.
Definition: openfabrics-verbs.h:134
-
hwloc_obj
Structure of a topology object.
Definition: hwloc.h:396
-
hwloc_obj::name
char * name
Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name str...
Definition: hwloc.h:408
-
hwloc_obj::attr
union hwloc_obj_attr_u * attr
Object type-specific Attributes, may be NULL if no attribute value was found.
Definition: hwloc.h:415
-
hwloc_obj_attr_u::osdev
struct hwloc_obj_attr_u::hwloc_osdev_attr_s osdev
-
hwloc_obj_attr_u::hwloc_osdev_attr_s::type
hwloc_obj_osdev_type_t type
Definition: hwloc.h:666
-
- - - - - - - - -
-
-
diff.h
-
-
-
1 /*
-
2  * Copyright © 2013-2020 Inria. All rights reserved.
-
3  * See COPYING in top-level directory.
-
4  */
-
5 
-
10 #ifndef HWLOC_DIFF_H
-
11 #define HWLOC_DIFF_H
-
12 
-
13 #ifndef HWLOC_H
-
14 #error Please include the main hwloc.h instead
-
15 #endif
-
16 
-
17 
-
18 #ifdef __cplusplus
-
19 extern "C" {
-
20 #elif 0
-
21 }
-
22 #endif
-
23 
-
24 
-
62 typedef enum hwloc_topology_diff_obj_attr_type_e {
-
67  HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_SIZE,
-
68 
-
74  HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_NAME,
-
78  HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_INFO
-
79 } hwloc_topology_diff_obj_attr_type_t;
-
80 
-
83 union hwloc_topology_diff_obj_attr_u {
-
84  struct hwloc_topology_diff_obj_attr_generic_s {
-
85  /* each part of the union must start with these */
-
86  hwloc_topology_diff_obj_attr_type_t type;
-
87  } generic;
-
88 
-
90  struct hwloc_topology_diff_obj_attr_uint64_s {
-
91  /* used for storing integer attributes */
-
92  hwloc_topology_diff_obj_attr_type_t type;
-
93  hwloc_uint64_t index; /* not used for SIZE */
-
94  hwloc_uint64_t oldvalue;
-
95  hwloc_uint64_t newvalue;
-
96  } uint64;
-
97 
-
99  struct hwloc_topology_diff_obj_attr_string_s {
-
100  /* used for storing name and info pairs */
-
101  hwloc_topology_diff_obj_attr_type_t type;
-
102  char *name; /* not used for NAME */
-
103  char *oldvalue;
-
104  char *newvalue;
-
105  } string;
-
106 };
-
107 
-
108 
-
111 typedef enum hwloc_topology_diff_type_e {
-
115  HWLOC_TOPOLOGY_DIFF_OBJ_ATTR,
-
116 
-
124  HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX
-
125 } hwloc_topology_diff_type_t;
-
126 
-
129 typedef union hwloc_topology_diff_u {
-
130  struct hwloc_topology_diff_generic_s {
-
131  /* each part of the union must start with these */
-
132  hwloc_topology_diff_type_t type;
-
133  union hwloc_topology_diff_u * next; /* pointer to the next element of the list, or NULL */
-
134  } generic;
-
135 
-
136  /* A difference in an object attribute. */
-
137  struct hwloc_topology_diff_obj_attr_s {
-
138  hwloc_topology_diff_type_t type; /* must be ::HWLOC_TOPOLOGY_DIFF_OBJ_ATTR */
-
139  union hwloc_topology_diff_u * next;
-
140  /* List of attribute differences for a single object */
-
141  int obj_depth;
-
142  unsigned obj_index;
-
143  union hwloc_topology_diff_obj_attr_u diff;
-
144  } obj_attr;
-
145 
-
146  /* A difference that is too complex. */
-
147  struct hwloc_topology_diff_too_complex_s {
-
148  hwloc_topology_diff_type_t type; /* must be ::HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX */
-
149  union hwloc_topology_diff_u * next;
-
150  /* Where we had to stop computing the diff in the first topology */
-
151  int obj_depth;
-
152  unsigned obj_index;
-
153  } too_complex;
-
154 } * hwloc_topology_diff_t;
-
155 
-
156 
-
194 HWLOC_DECLSPEC int hwloc_topology_diff_build(hwloc_topology_t topology, hwloc_topology_t newtopology, unsigned long flags, hwloc_topology_diff_t *diff);
-
195 
-
198 enum hwloc_topology_diff_apply_flags_e {
-
202  HWLOC_TOPOLOGY_DIFF_APPLY_REVERSE = (1UL<<0)
-
203 };
-
204 
-
222 HWLOC_DECLSPEC int hwloc_topology_diff_apply(hwloc_topology_t topology, hwloc_topology_diff_t diff, unsigned long flags);
-
223 
-
226 HWLOC_DECLSPEC int hwloc_topology_diff_destroy(hwloc_topology_diff_t diff);
-
227 
-
239 HWLOC_DECLSPEC int hwloc_topology_diff_load_xml(const char *xmlpath, hwloc_topology_diff_t *diff, char **refname);
-
240 
-
250 HWLOC_DECLSPEC int hwloc_topology_diff_export_xml(hwloc_topology_diff_t diff, const char *refname, const char *xmlpath);
-
251 
-
263 HWLOC_DECLSPEC int hwloc_topology_diff_load_xmlbuffer(const char *xmlbuffer, int buflen, hwloc_topology_diff_t *diff, char **refname);
-
264 
-
279 HWLOC_DECLSPEC int hwloc_topology_diff_export_xmlbuffer(hwloc_topology_diff_t diff, const char *refname, char **xmlbuffer, int *buflen);
-
280 
-
284 #ifdef __cplusplus
-
285 } /* extern "C" */
-
286 #endif
-
287 
-
288 
-
289 #endif /* HWLOC_DIFF_H */
-
hwloc_topology_t
struct hwloc_topology * hwloc_topology_t
Topology context.
Definition: hwloc.h:692
-
hwloc_topology_diff_t
union hwloc_topology_diff_u * hwloc_topology_diff_t
One element of a difference list between two topologies.
-
hwloc_topology_diff_load_xml
int hwloc_topology_diff_load_xml(const char *xmlpath, hwloc_topology_diff_t *diff, char **refname)
Load a list of topology differences from a XML file.
-
hwloc_topology_diff_type_e
hwloc_topology_diff_type_e
Type of one element of a difference list.
Definition: diff.h:111
-
hwloc_topology_diff_destroy
int hwloc_topology_diff_destroy(hwloc_topology_diff_t diff)
Destroy a list of topology differences.
-
hwloc_topology_diff_obj_attr_type_t
enum hwloc_topology_diff_obj_attr_type_e hwloc_topology_diff_obj_attr_type_t
Type of one object attribute difference.
-
hwloc_topology_diff_type_t
enum hwloc_topology_diff_type_e hwloc_topology_diff_type_t
Type of one element of a difference list.
-
hwloc_topology_diff_obj_attr_type_e
hwloc_topology_diff_obj_attr_type_e
Type of one object attribute difference.
Definition: diff.h:62
-
hwloc_topology_diff_export_xml
int hwloc_topology_diff_export_xml(hwloc_topology_diff_t diff, const char *refname, const char *xmlpath)
Export a list of topology differences to a XML file.
-
hwloc_topology_diff_build
int hwloc_topology_diff_build(hwloc_topology_t topology, hwloc_topology_t newtopology, unsigned long flags, hwloc_topology_diff_t *diff)
Compute the difference between 2 topologies.
-
hwloc_topology_diff_export_xmlbuffer
int hwloc_topology_diff_export_xmlbuffer(hwloc_topology_diff_t diff, const char *refname, char **xmlbuffer, int *buflen)
Export a list of topology differences to a XML buffer.
-
hwloc_topology_diff_load_xmlbuffer
int hwloc_topology_diff_load_xmlbuffer(const char *xmlbuffer, int buflen, hwloc_topology_diff_t *diff, char **refname)
Load a list of topology differences from a XML buffer.
-
hwloc_topology_diff_apply_flags_e
hwloc_topology_diff_apply_flags_e
Flags to be given to hwloc_topology_diff_apply().
Definition: diff.h:198
-
hwloc_topology_diff_apply
int hwloc_topology_diff_apply(hwloc_topology_t topology, hwloc_topology_diff_t diff, unsigned long flags)
Apply a topology diff to an existing topology.
-
HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX
@ HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX
The difference is too complex, it cannot be represented. The difference below this object has not bee...
Definition: diff.h:124
-
HWLOC_TOPOLOGY_DIFF_OBJ_ATTR
@ HWLOC_TOPOLOGY_DIFF_OBJ_ATTR
An object attribute was changed. The union is a hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s...
Definition: diff.h:115
-
HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_INFO
@ HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_INFO
the value of an info attribute is modified. The union is a hwloc_topology_diff_obj_attr_u::hwloc_topo...
Definition: diff.h:78
-
HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_NAME
@ HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_NAME
The object name is modified. The union is a hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_a...
Definition: diff.h:74
-
HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_SIZE
@ HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_SIZE
The object local memory is modified. The union is a hwloc_topology_diff_obj_attr_u::hwloc_topology_di...
Definition: diff.h:67
-
HWLOC_TOPOLOGY_DIFF_APPLY_REVERSE
@ HWLOC_TOPOLOGY_DIFF_APPLY_REVERSE
Apply topology diff in reverse direction.
Definition: diff.h:202
-
hwloc_topology_diff_obj_attr_u
One object attribute difference.
Definition: diff.h:83
-
hwloc_topology_diff_obj_attr_u::string
struct hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s string
-
hwloc_topology_diff_obj_attr_u::uint64
struct hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s uint64
- -
hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_generic_s::type
hwloc_topology_diff_obj_attr_type_t type
Definition: diff.h:86
-
hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s
Integer attribute modification with an optional index.
Definition: diff.h:90
- - - -
hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s::type
hwloc_topology_diff_obj_attr_type_t type
Definition: diff.h:92
-
hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s
String attribute modification with an optional name.
Definition: diff.h:99
- - -
hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s::type
hwloc_topology_diff_obj_attr_type_t type
Definition: diff.h:101
- -
hwloc_topology_diff_u
One element of a difference list between two topologies.
Definition: diff.h:129
- -
hwloc_topology_diff_u::hwloc_topology_diff_generic_s::type
hwloc_topology_diff_type_t type
Definition: diff.h:132
-
hwloc_topology_diff_u::hwloc_topology_diff_generic_s::next
union hwloc_topology_diff_u * next
Definition: diff.h:133
- -
hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s::type
hwloc_topology_diff_type_t type
Definition: diff.h:138
- -
hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s::next
union hwloc_topology_diff_u * next
Definition: diff.h:139
- -
hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s::next
union hwloc_topology_diff_u * next
Definition: diff.h:149
- -
hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s::type
hwloc_topology_diff_type_t type
Definition: diff.h:148
- -
- - - - - - - - -
-
-
shmem.h
-
-
-
1 /*
-
2  * Copyright © 2013-2018 Inria. All rights reserved.
-
3  * See COPYING in top-level directory.
-
4  */
-
5 
-
10 #ifndef HWLOC_SHMEM_H
-
11 #define HWLOC_SHMEM_H
-
12 
-
13 #include "hwloc.h"
-
14 
-
15 #ifdef __cplusplus
-
16 extern "C" {
-
17 #elif 0
-
18 }
-
19 #endif
-
20 
-
21 
-
53 HWLOC_DECLSPEC int hwloc_shmem_topology_get_length(hwloc_topology_t topology,
-
54  size_t *lengthp,
-
55  unsigned long flags);
-
56 
-
82 HWLOC_DECLSPEC int hwloc_shmem_topology_write(hwloc_topology_t topology,
-
83  int fd, hwloc_uint64_t fileoffset,
-
84  void *mmap_address, size_t length,
-
85  unsigned long flags);
-
86 
-
125 HWLOC_DECLSPEC int hwloc_shmem_topology_adopt(hwloc_topology_t *topologyp,
-
126  int fd, hwloc_uint64_t fileoffset,
-
127  void *mmap_address, size_t length,
-
128  unsigned long flags);
-
132 #ifdef __cplusplus
-
133 } /* extern "C" */
-
134 #endif
-
135 
-
136 
-
137 #endif /* HWLOC_SHMEM_H */
-
hwloc_topology_t
struct hwloc_topology * hwloc_topology_t
Topology context.
Definition: hwloc.h:692
-
hwloc_shmem_topology_adopt
int hwloc_shmem_topology_adopt(hwloc_topology_t *topologyp, int fd, hwloc_uint64_t fileoffset, void *mmap_address, size_t length, unsigned long flags)
Adopt a shared memory topology stored in a file.
-
hwloc_shmem_topology_write
int hwloc_shmem_topology_write(hwloc_topology_t topology, int fd, hwloc_uint64_t fileoffset, void *mmap_address, size_t length, unsigned long flags)
Duplicate a topology to a shared memory file.
-
hwloc_shmem_topology_get_length
int hwloc_shmem_topology_get_length(hwloc_topology_t topology, size_t *lengthp, unsigned long flags)
Get the required shared memory length for storing a topology.
-
- - - - - - - - -
-
-
plugins.h
-
-
-
1 /*
-
2  * Copyright © 2013-2022 Inria. All rights reserved.
-
3  * Copyright © 2016 Cisco Systems, Inc. All rights reserved.
-
4  * See COPYING in top-level directory.
-
5  */
-
6 
-
7 #ifndef HWLOC_PLUGINS_H
-
8 #define HWLOC_PLUGINS_H
-
9 
-
14 struct hwloc_backend;
-
15 
-
16 #include "hwloc.h"
-
17 
-
18 #ifdef HWLOC_INSIDE_PLUGIN
-
19 /* needed for hwloc_plugin_check_namespace() */
-
20 #ifdef HWLOC_HAVE_LTDL
-
21 #include <ltdl.h>
-
22 #else
-
23 #include <dlfcn.h>
-
24 #endif
-
25 #endif
-
26 
-
27 
-
28 
-
41 struct hwloc_disc_component {
-
45  const char *name;
-
46 
-
50  unsigned phases;
-
51 
-
60  unsigned excluded_phases;
-
61 
-
65  struct hwloc_backend * (*instantiate)(struct hwloc_topology *topology, struct hwloc_disc_component *component, unsigned excluded_phases, const void *data1, const void *data2, const void *data3);
-
66 
-
79  unsigned priority;
-
80 
-
84  unsigned enabled_by_default;
-
85 
-
90  struct hwloc_disc_component * next;
-
91 };
-
92 
-
106 typedef enum hwloc_disc_phase_e {
-
111  HWLOC_DISC_PHASE_GLOBAL = (1U<<0),
-
112 
-
115  HWLOC_DISC_PHASE_CPU = (1U<<1),
-
116 
-
119  HWLOC_DISC_PHASE_MEMORY = (1U<<2),
-
120 
-
123  HWLOC_DISC_PHASE_PCI = (1U<<3),
-
124 
-
127  HWLOC_DISC_PHASE_IO = (1U<<4),
-
128 
-
131  HWLOC_DISC_PHASE_MISC = (1U<<5),
-
132 
-
135  HWLOC_DISC_PHASE_ANNOTATE = (1U<<6),
-
136 
-
142  HWLOC_DISC_PHASE_TWEAK = (1U<<7)
-
143 } hwloc_disc_phase_t;
-
144 
-
146 enum hwloc_disc_status_flag_e {
-
148  HWLOC_DISC_STATUS_FLAG_GOT_ALLOWED_RESOURCES = (1UL<<1)
-
149 };
-
150 
-
156 struct hwloc_disc_status {
-
160  hwloc_disc_phase_t phase;
-
161 
-
165  unsigned excluded_phases;
-
166 
-
168  unsigned long flags;
-
169 };
-
170 
-
189 struct hwloc_backend {
-
191  struct hwloc_disc_component * component;
-
193  struct hwloc_topology * topology;
-
195  int envvar_forced;
-
197  struct hwloc_backend * next;
-
198 
-
202  unsigned phases;
-
203 
-
205  unsigned long flags;
-
206 
-
213  int is_thissystem;
-
214 
-
216  void * private_data;
-
220  void (*disable)(struct hwloc_backend *backend);
-
221 
-
227  int (*discover)(struct hwloc_backend *backend, struct hwloc_disc_status *status);
-
228 
-
233  int (*get_pci_busid_cpuset)(struct hwloc_backend *backend, struct hwloc_pcidev_attr_s *busid, hwloc_bitmap_t cpuset);
-
234 };
-
235 
-
239 HWLOC_DECLSPEC struct hwloc_backend * hwloc_backend_alloc(struct hwloc_topology *topology, struct hwloc_disc_component *component);
-
240 
-
242 HWLOC_DECLSPEC int hwloc_backend_enable(struct hwloc_backend *backend);
-
243 
-
257 typedef enum hwloc_component_type_e {
-
259  HWLOC_COMPONENT_TYPE_DISC,
-
260 
-
262  HWLOC_COMPONENT_TYPE_XML
-
263 } hwloc_component_type_t;
-
264 
-
270 struct hwloc_component {
-
272  unsigned abi;
-
273 
-
291  int (*init)(unsigned long flags);
-
292 
-
304  void (*finalize)(unsigned long flags);
-
305 
-
307  hwloc_component_type_t type;
-
308 
-
310  unsigned long flags;
-
311 
-
313  void * data;
-
314 };
-
315 
-
345 HWLOC_DECLSPEC int hwloc_hide_errors(void);
-
346 
-
347 #define HWLOC_SHOW_CRITICAL_ERRORS() (hwloc_hide_errors() < 2)
-
348 #define HWLOC_SHOW_ALL_ERRORS() (hwloc_hide_errors() == 0)
-
349 
-
378 HWLOC_DECLSPEC hwloc_obj_t
-
379 hwloc__insert_object_by_cpuset(struct hwloc_topology *topology, hwloc_obj_t root,
-
380  hwloc_obj_t obj, const char *reason);
-
381 
-
398 HWLOC_DECLSPEC void hwloc_insert_object_by_parent(struct hwloc_topology *topology, hwloc_obj_t parent, hwloc_obj_t obj);
-
399 
-
404 HWLOC_DECLSPEC hwloc_obj_t hwloc_alloc_setup_object(hwloc_topology_t topology, hwloc_obj_type_t type, unsigned os_index);
-
405 
-
414 HWLOC_DECLSPEC int hwloc_obj_add_children_sets(hwloc_obj_t obj);
-
415 
-
423 HWLOC_DECLSPEC int hwloc_topology_reconnect(hwloc_topology_t topology, unsigned long flags __hwloc_attribute_unused);
-
424 
-
446 static __hwloc_inline int
-
447 hwloc_plugin_check_namespace(const char *pluginname __hwloc_attribute_unused, const char *symbol __hwloc_attribute_unused)
-
448 {
-
449 #ifdef HWLOC_INSIDE_PLUGIN
-
450  void *sym;
-
451 #ifdef HWLOC_HAVE_LTDL
-
452  lt_dlhandle handle = lt_dlopen(NULL);
-
453 #else
-
454  void *handle = dlopen(NULL, RTLD_NOW|RTLD_LOCAL);
-
455 #endif
-
456  if (!handle)
-
457  /* cannot check, assume things will work */
-
458  return 0;
-
459 #ifdef HWLOC_HAVE_LTDL
-
460  sym = lt_dlsym(handle, symbol);
-
461  lt_dlclose(handle);
-
462 #else
-
463  sym = dlsym(handle, symbol);
-
464  dlclose(handle);
-
465 #endif
-
466  if (!sym) {
-
467  static int verboseenv_checked = 0;
-
468  static int verboseenv_value = 0;
-
469  if (!verboseenv_checked) {
-
470  const char *verboseenv = getenv("HWLOC_PLUGINS_VERBOSE");
-
471  verboseenv_value = verboseenv ? atoi(verboseenv) : 0;
-
472  verboseenv_checked = 1;
-
473  }
-
474  if (verboseenv_value)
-
475  fprintf(stderr, "Plugin `%s' disabling itself because it cannot find the `%s' core symbol.\n",
-
476  pluginname, symbol);
-
477  return -1;
-
478  }
-
479 #endif /* HWLOC_INSIDE_PLUGIN */
-
480  return 0;
-
481 }
-
482 
-
499 static __hwloc_inline int
-
500 hwloc_filter_check_pcidev_subtype_important(unsigned classid)
-
501 {
-
502  unsigned baseclass = classid >> 8;
-
503  return (baseclass == 0x03 /* PCI_BASE_CLASS_DISPLAY */
-
504  || baseclass == 0x02 /* PCI_BASE_CLASS_NETWORK */
-
505  || baseclass == 0x01 /* PCI_BASE_CLASS_STORAGE */
-
506  || baseclass == 0x00 /* Unclassified, for Atos/Bull BXI */
-
507  || baseclass == 0x0b /* PCI_BASE_CLASS_PROCESSOR */
-
508  || classid == 0x0c04 /* PCI_CLASS_SERIAL_FIBER */
-
509  || classid == 0x0c06 /* PCI_CLASS_SERIAL_INFINIBAND */
-
510  || classid == 0x0502 /* PCI_CLASS_MEMORY_CXL */
-
511  || baseclass == 0x06 /* PCI_BASE_CLASS_BRIDGE with non-PCI downstream. the core will drop the useless ones later */
-
512  || baseclass == 0x12 /* Processing Accelerators */);
-
513 }
-
514 
-
519 static __hwloc_inline int
-
520 hwloc_filter_check_osdev_subtype_important(hwloc_obj_osdev_type_t subtype)
-
521 {
-
522  return (subtype != HWLOC_OBJ_OSDEV_DMA);
-
523 }
-
524 
-
531 static __hwloc_inline int
-
532 hwloc_filter_check_keep_object_type(hwloc_topology_t topology, hwloc_obj_type_t type)
-
533 {
-
534  enum hwloc_type_filter_e filter = HWLOC_TYPE_FILTER_KEEP_NONE;
-
535  hwloc_topology_get_type_filter(topology, type, &filter);
-
536  assert(filter != HWLOC_TYPE_FILTER_KEEP_IMPORTANT); /* IMPORTANT only used for I/O */
-
537  return filter == HWLOC_TYPE_FILTER_KEEP_NONE ? 0 : 1;
-
538 }
-
539 
-
544 static __hwloc_inline int
-
545 hwloc_filter_check_keep_object(hwloc_topology_t topology, hwloc_obj_t obj)
-
546 {
-
547  hwloc_obj_type_t type = obj->type;
-
548  enum hwloc_type_filter_e filter = HWLOC_TYPE_FILTER_KEEP_NONE;
-
549  hwloc_topology_get_type_filter(topology, type, &filter);
-
550  if (filter == HWLOC_TYPE_FILTER_KEEP_NONE)
-
551  return 0;
-
552  if (filter == HWLOC_TYPE_FILTER_KEEP_IMPORTANT) {
-
553  if (type == HWLOC_OBJ_PCI_DEVICE)
-
554  return hwloc_filter_check_pcidev_subtype_important(obj->attr->pcidev.class_id);
-
555  if (type == HWLOC_OBJ_OS_DEVICE)
-
556  return hwloc_filter_check_osdev_subtype_important(obj->attr->osdev.type);
-
557  }
-
558  return 1;
-
559 }
-
560 
-
577 HWLOC_DECLSPEC unsigned hwloc_pcidisc_find_cap(const unsigned char *config, unsigned cap);
-
578 
-
584 HWLOC_DECLSPEC int hwloc_pcidisc_find_linkspeed(const unsigned char *config, unsigned offset, float *linkspeed);
-
585 
-
590 HWLOC_DECLSPEC hwloc_obj_type_t hwloc_pcidisc_check_bridge_type(unsigned device_class, const unsigned char *config);
-
591 
-
598 HWLOC_DECLSPEC int hwloc_pcidisc_find_bridge_buses(unsigned domain, unsigned bus, unsigned dev, unsigned func,
-
599  unsigned *secondary_busp, unsigned *subordinate_busp,
-
600  const unsigned char *config);
-
601 
-
606 HWLOC_DECLSPEC void hwloc_pcidisc_tree_insert_by_busid(struct hwloc_obj **treep, struct hwloc_obj *obj);
-
607 
-
613 HWLOC_DECLSPEC int hwloc_pcidisc_tree_attach(struct hwloc_topology *topology, struct hwloc_obj *tree);
-
614 
-
638 HWLOC_DECLSPEC struct hwloc_obj * hwloc_pci_find_parent_by_busid(struct hwloc_topology *topology, unsigned domain, unsigned bus, unsigned dev, unsigned func);
-
639 
-
646 HWLOC_DECLSPEC struct hwloc_obj * hwloc_pci_find_by_busid(struct hwloc_topology *topology, unsigned domain, unsigned bus, unsigned dev, unsigned func);
-
647 
-
649 typedef void * hwloc_backend_distances_add_handle_t;
-
650 
-
657 HWLOC_DECLSPEC hwloc_backend_distances_add_handle_t
-
658 hwloc_backend_distances_add_create(hwloc_topology_t topology,
-
659  const char *name, unsigned long kind,
-
660  unsigned long flags);
-
661 
-
673 HWLOC_DECLSPEC int
-
674 hwloc_backend_distances_add_values(hwloc_topology_t topology,
-
675  hwloc_backend_distances_add_handle_t handle,
-
676  unsigned nbobjs, hwloc_obj_t *objs,
-
677  hwloc_uint64_t *values,
-
678  unsigned long flags);
-
679 
-
686 HWLOC_DECLSPEC int
-
687 hwloc_backend_distances_add_commit(hwloc_topology_t topology,
-
688  hwloc_backend_distances_add_handle_t handle,
-
689  unsigned long flags);
-
690 
-
696 #endif /* HWLOC_PLUGINS_H */
-
hwloc_obj_osdev_type_t
enum hwloc_obj_osdev_type_e hwloc_obj_osdev_type_t
Type of a OS device.
-
hwloc_obj_type_t
hwloc_obj_type_t
Type of topology object.
Definition: hwloc.h:176
-
HWLOC_OBJ_OSDEV_DMA
@ HWLOC_OBJ_OSDEV_DMA
Operating system dma engine device. For instance the "dma0chan0" DMA channel on Linux.
Definition: hwloc.h:351
-
HWLOC_OBJ_OS_DEVICE
@ HWLOC_OBJ_OS_DEVICE
Operating system device (filtered out by default).
Definition: hwloc.h:279
-
HWLOC_OBJ_PCI_DEVICE
@ HWLOC_OBJ_PCI_DEVICE
PCI device (filtered out by default).
Definition: hwloc.h:269
-
hwloc_topology_t
struct hwloc_topology * hwloc_topology_t
Topology context.
Definition: hwloc.h:692
-
hwloc_topology_get_type_filter
int hwloc_topology_get_type_filter(hwloc_topology_t topology, hwloc_obj_type_t type, enum hwloc_type_filter_e *filter)
Get the current filtering for the given object type.
-
hwloc_type_filter_e
hwloc_type_filter_e
Type filtering flags.
Definition: hwloc.h:2254
-
HWLOC_TYPE_FILTER_KEEP_NONE
@ HWLOC_TYPE_FILTER_KEEP_NONE
Ignore all objects of this type.
Definition: hwloc.h:2268
-
HWLOC_TYPE_FILTER_KEEP_IMPORTANT
@ HWLOC_TYPE_FILTER_KEEP_IMPORTANT
Only keep likely-important objects of the given type.
Definition: hwloc.h:2297
-
hwloc_bitmap_t
struct hwloc_bitmap_s * hwloc_bitmap_t
Set of bits represented as an opaque pointer to an internal bitmap.
Definition: bitmap.h:68
-
hwloc_backend_enable
int hwloc_backend_enable(struct hwloc_backend *backend)
Enable a previously allocated and setup backend.
-
hwloc_disc_phase_t
enum hwloc_disc_phase_e hwloc_disc_phase_t
Discovery phase.
-
hwloc_disc_phase_e
hwloc_disc_phase_e
Discovery phase.
Definition: plugins.h:106
-
hwloc_disc_status_flag_e
hwloc_disc_status_flag_e
Discovery status flags.
Definition: plugins.h:146
-
hwloc_backend_alloc
struct hwloc_backend * hwloc_backend_alloc(struct hwloc_topology *topology, struct hwloc_disc_component *component)
Allocate a backend structure, set good default values, initialize backend->component and topology,...
-
HWLOC_DISC_PHASE_CPU
@ HWLOC_DISC_PHASE_CPU
CPU discovery.
Definition: plugins.h:115
-
HWLOC_DISC_PHASE_PCI
@ HWLOC_DISC_PHASE_PCI
Attach PCI devices and bridges to existing CPU objects.
Definition: plugins.h:123
-
HWLOC_DISC_PHASE_ANNOTATE
@ HWLOC_DISC_PHASE_ANNOTATE
Annotating existing objects, adding distances, etc.
Definition: plugins.h:135
-
HWLOC_DISC_PHASE_MISC
@ HWLOC_DISC_PHASE_MISC
Misc objects that gets added below anything else.
Definition: plugins.h:131
-
HWLOC_DISC_PHASE_IO
@ HWLOC_DISC_PHASE_IO
I/O discovery that requires PCI devices (OS devices such as OpenCL, CUDA, etc.).
Definition: plugins.h:127
-
HWLOC_DISC_PHASE_GLOBAL
@ HWLOC_DISC_PHASE_GLOBAL
xml or synthetic, platform-specific components such as bgq. Discovers everything including CPU,...
Definition: plugins.h:111
-
HWLOC_DISC_PHASE_MEMORY
@ HWLOC_DISC_PHASE_MEMORY
Attach memory to existing CPU objects.
Definition: plugins.h:119
-
HWLOC_DISC_PHASE_TWEAK
@ HWLOC_DISC_PHASE_TWEAK
Final tweaks to a ready-to-use topology. This phase runs once the topology is loaded,...
Definition: plugins.h:142
-
HWLOC_DISC_STATUS_FLAG_GOT_ALLOWED_RESOURCES
@ HWLOC_DISC_STATUS_FLAG_GOT_ALLOWED_RESOURCES
The sets of allowed resources were already retrieved.
Definition: plugins.h:148
-
hwloc_component_type_t
enum hwloc_component_type_e hwloc_component_type_t
Generic component type.
-
hwloc_component_type_e
hwloc_component_type_e
Generic component type.
Definition: plugins.h:257
-
HWLOC_COMPONENT_TYPE_DISC
@ HWLOC_COMPONENT_TYPE_DISC
The data field must point to a struct hwloc_disc_component.
Definition: plugins.h:259
-
HWLOC_COMPONENT_TYPE_XML
@ HWLOC_COMPONENT_TYPE_XML
The data field must point to a struct hwloc_xml_component.
Definition: plugins.h:262
-
hwloc_alloc_setup_object
hwloc_obj_t hwloc_alloc_setup_object(hwloc_topology_t topology, hwloc_obj_type_t type, unsigned os_index)
Allocate and initialize an object of the given type and physical index.
-
hwloc_insert_object_by_parent
void hwloc_insert_object_by_parent(struct hwloc_topology *topology, hwloc_obj_t parent, hwloc_obj_t obj)
Insert an object somewhere in the topology.
-
hwloc_topology_reconnect
int hwloc_topology_reconnect(hwloc_topology_t topology, unsigned long flags)
Request a reconnection of children and levels in the topology.
-
hwloc__insert_object_by_cpuset
hwloc_obj_t hwloc__insert_object_by_cpuset(struct hwloc_topology *topology, hwloc_obj_t root, hwloc_obj_t obj, const char *reason)
Add an object to the topology.
-
hwloc_obj_add_children_sets
int hwloc_obj_add_children_sets(hwloc_obj_t obj)
Setup object cpusets/nodesets by OR'ing its children.
-
hwloc_hide_errors
int hwloc_hide_errors(void)
Check whether error messages are hidden.
-
hwloc_plugin_check_namespace
static int hwloc_plugin_check_namespace(const char *pluginname, const char *symbol)
Make sure that plugins can lookup core symbols.
Definition: plugins.h:447
-
hwloc_filter_check_keep_object_type
static int hwloc_filter_check_keep_object_type(hwloc_topology_t topology, hwloc_obj_type_t type)
Check whether a non-I/O object type should be filtered-out.
Definition: plugins.h:532
-
hwloc_filter_check_keep_object
static int hwloc_filter_check_keep_object(hwloc_topology_t topology, hwloc_obj_t obj)
Check whether the given object should be filtered-out.
Definition: plugins.h:545
-
hwloc_filter_check_pcidev_subtype_important
static int hwloc_filter_check_pcidev_subtype_important(unsigned classid)
Check whether the given PCI device classid is important.
Definition: plugins.h:500
-
hwloc_filter_check_osdev_subtype_important
static int hwloc_filter_check_osdev_subtype_important(hwloc_obj_osdev_type_t subtype)
Check whether the given OS device subtype is important.
Definition: plugins.h:520
-
hwloc_pcidisc_find_linkspeed
int hwloc_pcidisc_find_linkspeed(const unsigned char *config, unsigned offset, float *linkspeed)
Fill linkspeed by reading the PCI config space where PCI_CAP_ID_EXP is at position offset.
-
hwloc_pcidisc_check_bridge_type
hwloc_obj_type_t hwloc_pcidisc_check_bridge_type(unsigned device_class, const unsigned char *config)
Return the hwloc object type (PCI device or Bridge) for the given class and configuration space.
-
hwloc_pcidisc_find_cap
unsigned hwloc_pcidisc_find_cap(const unsigned char *config, unsigned cap)
Return the offset of the given capability in the PCI config space buffer.
-
hwloc_pcidisc_find_bridge_buses
int hwloc_pcidisc_find_bridge_buses(unsigned domain, unsigned bus, unsigned dev, unsigned func, unsigned *secondary_busp, unsigned *subordinate_busp, const unsigned char *config)
Fills the attributes of the given PCI bridge using the given PCI config space.
-
hwloc_pcidisc_tree_insert_by_busid
void hwloc_pcidisc_tree_insert_by_busid(struct hwloc_obj **treep, struct hwloc_obj *obj)
Insert a PCI object in the given PCI tree by looking at PCI bus IDs.
-
hwloc_pcidisc_tree_attach
int hwloc_pcidisc_tree_attach(struct hwloc_topology *topology, struct hwloc_obj *tree)
Add some hostbridges on top of the given tree of PCI objects and attach them to the topology.
-
hwloc_backend_distances_add_commit
int hwloc_backend_distances_add_commit(hwloc_topology_t topology, hwloc_backend_distances_add_handle_t handle, unsigned long flags)
Commit a new distances structure.
-
hwloc_pci_find_by_busid
struct hwloc_obj * hwloc_pci_find_by_busid(struct hwloc_topology *topology, unsigned domain, unsigned bus, unsigned dev, unsigned func)
Find the PCI device or bridge matching a PCI bus ID exactly.
-
hwloc_pci_find_parent_by_busid
struct hwloc_obj * hwloc_pci_find_parent_by_busid(struct hwloc_topology *topology, unsigned domain, unsigned bus, unsigned dev, unsigned func)
Find the object or a parent of a PCI bus ID.
-
hwloc_backend_distances_add_values
int hwloc_backend_distances_add_values(hwloc_topology_t topology, hwloc_backend_distances_add_handle_t handle, unsigned nbobjs, hwloc_obj_t *objs, hwloc_uint64_t *values, unsigned long flags)
Specify the objects and values in a new empty distances structure.
-
hwloc_backend_distances_add_create
hwloc_backend_distances_add_handle_t hwloc_backend_distances_add_create(hwloc_topology_t topology, const char *name, unsigned long kind, unsigned long flags)
Create a new empty distances structure.
-
hwloc_backend_distances_add_handle_t
void * hwloc_backend_distances_add_handle_t
Handle to a new distances structure during its addition to the topology.
Definition: plugins.h:649
-
hwloc_obj
Structure of a topology object.
Definition: hwloc.h:396
-
hwloc_obj::name
char * name
Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name str...
Definition: hwloc.h:408
-
hwloc_obj::type
hwloc_obj_type_t type
Type of object.
Definition: hwloc.h:398
-
hwloc_obj::attr
union hwloc_obj_attr_u * attr
Object type-specific Attributes, may be NULL if no attribute value was found.
Definition: hwloc.h:415
-
hwloc_obj_attr_u::pcidev
struct hwloc_obj_attr_u::hwloc_pcidev_attr_s pcidev
-
hwloc_obj_attr_u::osdev
struct hwloc_obj_attr_u::hwloc_osdev_attr_s osdev
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s::class_id
unsigned short class_id
Definition: hwloc.h:640
-
hwloc_obj_attr_u::hwloc_osdev_attr_s::type
hwloc_obj_osdev_type_t type
Definition: hwloc.h:666
-
hwloc_disc_component
Discovery component structure.
Definition: plugins.h:41
-
hwloc_disc_component::name
const char * name
Name. If this component is built as a plugin, this name does not have to match the plugin filename.
Definition: plugins.h:45
-
hwloc_disc_component::phases
unsigned phases
Discovery phases performed by this component. OR'ed set of hwloc_disc_phase_t.
Definition: plugins.h:50
-
hwloc_disc_component::excluded_phases
unsigned excluded_phases
Component phases to exclude, as an OR'ed set of hwloc_disc_phase_t.
Definition: plugins.h:60
-
hwloc_disc_component::enabled_by_default
unsigned enabled_by_default
Enabled by default. If unset, if will be disabled unless explicitly requested.
Definition: plugins.h:84
-
hwloc_disc_component::priority
unsigned priority
Component priority. Used to sort topology->components, higher priority first. Also used to decide bet...
Definition: plugins.h:79
-
hwloc_disc_status
Discovery status structure.
Definition: plugins.h:156
-
hwloc_disc_status::excluded_phases
unsigned excluded_phases
Dynamically excluded phases. If a component decides during discovery that some phases are no longer n...
Definition: plugins.h:165
-
hwloc_disc_status::phase
hwloc_disc_phase_t phase
The current discovery phase that is performed. Must match one of the phases in the component phases f...
Definition: plugins.h:160
-
hwloc_disc_status::flags
unsigned long flags
OR'ed set of hwloc_disc_status_flag_e.
Definition: plugins.h:168
-
hwloc_backend
Discovery backend structure.
Definition: plugins.h:189
-
hwloc_backend::private_data
void * private_data
Backend private data, or NULL if none.
Definition: plugins.h:216
-
hwloc_backend::disable
void(* disable)(struct hwloc_backend *backend)
Callback for freeing the private_data. May be NULL.
Definition: plugins.h:220
-
hwloc_backend::flags
unsigned long flags
Backend flags, currently always 0.
Definition: plugins.h:205
-
hwloc_backend::get_pci_busid_cpuset
int(* get_pci_busid_cpuset)(struct hwloc_backend *backend, struct hwloc_pcidev_attr_s *busid, hwloc_bitmap_t cpuset)
Callback to retrieve the locality of a PCI object. Called by the PCI core when attaching PCI hierarch...
Definition: plugins.h:233
-
hwloc_backend::is_thissystem
int is_thissystem
Backend-specific 'is_thissystem' property. Set to 0 if the backend disables the thissystem flag for t...
Definition: plugins.h:213
-
hwloc_backend::discover
int(* discover)(struct hwloc_backend *backend, struct hwloc_disc_status *status)
Main discovery callback. returns -1 on error, either because it couldn't add its objects ot the exist...
Definition: plugins.h:227
-
hwloc_backend::phases
unsigned phases
Discovery phases performed by this component, possibly without some of them if excluded by other comp...
Definition: plugins.h:202
-
hwloc_component
Generic component structure.
Definition: plugins.h:270
-
hwloc_component::abi
unsigned abi
Component ABI version, set to HWLOC_COMPONENT_ABI.
Definition: plugins.h:272
-
hwloc_component::finalize
void(* finalize)(unsigned long flags)
Process-wide component termination callback.
Definition: plugins.h:304
-
hwloc_component::data
void * data
Component data, pointing to a struct hwloc_disc_component or struct hwloc_xml_component.
Definition: plugins.h:313
-
hwloc_component::type
hwloc_component_type_t type
Component type.
Definition: plugins.h:307
-
hwloc_component::flags
unsigned long flags
Component flags, unused for now.
Definition: plugins.h:310
-
hwloc_component::init
int(* init)(unsigned long flags)
Process-wide component initialization callback.
Definition: plugins.h:291
-
- - - - - - - - -
-
-
netloc.h
-
-
-
1 /*
-
2  * Copyright © 2013-2014 Cisco Systems, Inc. All rights reserved.
-
3  * Copyright © 2013-2014 University of Wisconsin-La Crosse.
-
4  * All rights reserved.
-
5  * Copyright © 2015-2016 Inria. All rights reserved.
-
6  *
-
7  * $COPYRIGHT$
-
8  *
-
9  * Additional copyrights may follow
-
10  * See COPYING in top-level directory.
-
11  *
-
12  * $HEADER$
-
13  */
-
14 
-
15 #ifndef _NETLOC_H_
-
16 #define _NETLOC_H_
-
17 
-
18 #ifndef _GNU_SOURCE
-
19 #define _GNU_SOURCE // for asprintf
-
20 #endif
-
21 
-
22 #include <hwloc/autogen/config.h>
-
23 
-
24 #include <hwloc.h>
-
25 
-
26 #ifdef __cplusplus
-
27 extern "C" {
-
28 #endif
-
29 
-
36 enum {
-
37  NETLOC_SUCCESS = 0,
-
38  NETLOC_ERROR = -1,
-
39  NETLOC_ERROR_NOTDIR = -2,
-
40  NETLOC_ERROR_NOENT = -3,
-
41  NETLOC_ERROR_EMPTY = -4,
-
42  NETLOC_ERROR_MULTIPLE = -5,
-
43  NETLOC_ERROR_NOT_IMPL = -6,
-
44  NETLOC_ERROR_EXISTS = -7,
-
45  NETLOC_ERROR_NOT_FOUND = -8,
-
46  NETLOC_ERROR_MAX = -9
-
47 };
-
48 
-
49 
-
50 #ifdef __cplusplus
-
51 } /* extern "C" */
-
52 #endif
-
53 
-
56 #endif // _NETLOC_H_
-
NETLOC_ERROR_EMPTY
@ NETLOC_ERROR_EMPTY
Definition: netloc.h:41
-
NETLOC_ERROR_MAX
@ NETLOC_ERROR_MAX
Definition: netloc.h:46
-
NETLOC_ERROR_MULTIPLE
@ NETLOC_ERROR_MULTIPLE
Definition: netloc.h:42
-
NETLOC_ERROR_NOT_IMPL
@ NETLOC_ERROR_NOT_IMPL
Definition: netloc.h:43
-
NETLOC_ERROR
@ NETLOC_ERROR
Definition: netloc.h:38
-
NETLOC_SUCCESS
@ NETLOC_SUCCESS
Definition: netloc.h:37
-
NETLOC_ERROR_NOT_FOUND
@ NETLOC_ERROR_NOT_FOUND
Definition: netloc.h:45
-
NETLOC_ERROR_EXISTS
@ NETLOC_ERROR_EXISTS
Definition: netloc.h:44
-
NETLOC_ERROR_NOTDIR
@ NETLOC_ERROR_NOTDIR
Definition: netloc.h:39
-
NETLOC_ERROR_NOENT
@ NETLOC_ERROR_NOENT
Definition: netloc.h:40
-
- - - - - - - -
-
-Macros | -Functions
-
-
API version
-
-
- - - - - - -

-Macros

#define HWLOC_API_VERSION   0x00020800
 
#define HWLOC_COMPONENT_ABI   7
 
- - - -

-Functions

unsigned hwloc_get_api_version (void)
 
-

Detailed Description

-

Macro Definition Documentation

- -

◆ HWLOC_API_VERSION

- -
-
- - - - -
#define HWLOC_API_VERSION   0x00020800
-
- -

Indicate at build time which hwloc API version is being used.

-

This number is updated to (X<<16)+(Y<<8)+Z when a new release X.Y.Z actually modifies the API.

-

Users may check for available features at build time using this number (see How do I handle API changes?).

-
Note
This should not be confused with HWLOC_VERSION, the library version. Two stable releases of the same series usually have the same HWLOC_API_VERSION even if their HWLOC_VERSION are different.
- -
-
- -

◆ HWLOC_COMPONENT_ABI

- -
-
- - - - -
#define HWLOC_COMPONENT_ABI   7
-
- -

Current component and plugin ABI version (see hwloc/plugins.h)

- -
-
-

Function Documentation

- -

◆ hwloc_get_api_version()

- -
-
- - - - - - - - -
unsigned hwloc_get_api_version (void )
-
- -

Indicate at runtime which hwloc API version was used at build time.

-

Should be HWLOC_API_VERSION if running on the same version.

- -
-
-
- - - - - - - -
-
-Typedefs
-
-
Object Sets (hwloc_cpuset_t and hwloc_nodeset_t)
-
-
- - - - - - - - - - -

-Typedefs

typedef hwloc_bitmap_t hwloc_cpuset_t
 
typedef hwloc_const_bitmap_t hwloc_const_cpuset_t
 
typedef hwloc_bitmap_t hwloc_nodeset_t
 
typedef hwloc_const_bitmap_t hwloc_const_nodeset_t
 
-

Detailed Description

-

Hwloc uses bitmaps to represent two distinct kinds of object sets: CPU sets (hwloc_cpuset_t) and NUMA node sets (hwloc_nodeset_t). These types are both typedefs to a common back end type (hwloc_bitmap_t), and therefore all the hwloc bitmap functions are applicable to both hwloc_cpuset_t and hwloc_nodeset_t (see The bitmap API).

-

The rationale for having two different types is that even though the actions one wants to perform on these types are the same (e.g., enable and disable individual items in the set/mask), they're used in very different contexts: one for specifying which processors to use and one for specifying which NUMA nodes to use. Hence, the name difference is really just to reflect the intent of where the type is used.

-

Typedef Documentation

- -

◆ hwloc_const_cpuset_t

- -
-
- - - - -
typedef hwloc_const_bitmap_t hwloc_const_cpuset_t
-
- -

A non-modifiable hwloc_cpuset_t.

- -
-
- -

◆ hwloc_const_nodeset_t

- -
-
- - - - -
typedef hwloc_const_bitmap_t hwloc_const_nodeset_t
-
- -

A non-modifiable hwloc_nodeset_t.

- -
-
- -

◆ hwloc_cpuset_t

- -
-
- - - - -
typedef hwloc_bitmap_t hwloc_cpuset_t
-
- -

A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.

-

It may be consulted and modified with the bitmap API as any hwloc_bitmap_t (see hwloc/bitmap.h).

-

Each bit may be converted into a PU object using hwloc_get_pu_obj_by_os_index().

- -
-
- -

◆ hwloc_nodeset_t

- -
-
- - - - -
typedef hwloc_bitmap_t hwloc_nodeset_t
-
- -

A node set is a bitmap whose bits are set according to NUMA memory node physical OS indexes.

-

It may be consulted and modified with the bitmap API as any hwloc_bitmap_t (see hwloc/bitmap.h). Each bit may be converted into a NUMA node object using hwloc_get_numanode_obj_by_os_index().

-

When binding memory on a system without any NUMA node, the single main memory bank is considered as NUMA node #0.

-

See also Converting between CPU sets and node sets.

- -
-
-
- - - - - - - -
-
-Macros | -Typedefs | -Enumerations | -Functions
-
-
Object Types
-
-
- - - - -

-Macros

#define HWLOC_TYPE_UNORDERED
 
- - - - - - - -

-Typedefs

typedef enum hwloc_obj_cache_type_e hwloc_obj_cache_type_t
 
typedef enum hwloc_obj_bridge_type_e hwloc_obj_bridge_type_t
 
typedef enum hwloc_obj_osdev_type_e hwloc_obj_osdev_type_t
 
- - - - - - - - - -

-Enumerations

enum  hwloc_obj_type_t {
-  HWLOC_OBJ_MACHINE -, HWLOC_OBJ_PACKAGE -, HWLOC_OBJ_CORE -, HWLOC_OBJ_PU -,
-  HWLOC_OBJ_L1CACHE -, HWLOC_OBJ_L2CACHE -, HWLOC_OBJ_L3CACHE -, HWLOC_OBJ_L4CACHE -,
-  HWLOC_OBJ_L5CACHE -, HWLOC_OBJ_L1ICACHE -, HWLOC_OBJ_L2ICACHE -, HWLOC_OBJ_L3ICACHE -,
-  HWLOC_OBJ_GROUP -, HWLOC_OBJ_NUMANODE -, HWLOC_OBJ_BRIDGE -, HWLOC_OBJ_PCI_DEVICE -,
-  HWLOC_OBJ_OS_DEVICE -, HWLOC_OBJ_MISC -, HWLOC_OBJ_MEMCACHE -, HWLOC_OBJ_DIE -,
-  HWLOC_OBJ_TYPE_MAX -
- }
 
enum  hwloc_obj_cache_type_e { HWLOC_OBJ_CACHE_UNIFIED -, HWLOC_OBJ_CACHE_DATA -, HWLOC_OBJ_CACHE_INSTRUCTION - }
 
enum  hwloc_obj_bridge_type_e { HWLOC_OBJ_BRIDGE_HOST -, HWLOC_OBJ_BRIDGE_PCI - }
 
enum  hwloc_obj_osdev_type_e {
-  HWLOC_OBJ_OSDEV_BLOCK -, HWLOC_OBJ_OSDEV_GPU -, HWLOC_OBJ_OSDEV_NETWORK -, HWLOC_OBJ_OSDEV_OPENFABRICS -,
-  HWLOC_OBJ_OSDEV_DMA -, HWLOC_OBJ_OSDEV_COPROC -
- }
 
- - - -

-Functions

int hwloc_compare_types (hwloc_obj_type_t type1, hwloc_obj_type_t type2)
 
-

Detailed Description

-

Macro Definition Documentation

- -

◆ HWLOC_TYPE_UNORDERED

- -
-
- - - - -
#define HWLOC_TYPE_UNORDERED
-
- -

Value returned by hwloc_compare_types() when types can not be compared.

- -
-
-

Typedef Documentation

- -

◆ hwloc_obj_bridge_type_t

- -
-
- - - - -
typedef enum hwloc_obj_bridge_type_e hwloc_obj_bridge_type_t
-
- -

Type of one side (upstream or downstream) of an I/O bridge.

- -
-
- -

◆ hwloc_obj_cache_type_t

- -
-
- - - - -
typedef enum hwloc_obj_cache_type_e hwloc_obj_cache_type_t
-
- -

Cache type.

- -
-
- -

◆ hwloc_obj_osdev_type_t

- -
-
- - - - -
typedef enum hwloc_obj_osdev_type_e hwloc_obj_osdev_type_t
-
- -

Type of a OS device.

- -
-
-

Enumeration Type Documentation

- -

◆ hwloc_obj_bridge_type_e

- -
-
- - - - -
enum hwloc_obj_bridge_type_e
-
- -

Type of one side (upstream or downstream) of an I/O bridge.

- - - -
Enumerator
HWLOC_OBJ_BRIDGE_HOST 

Host-side of a bridge, only possible upstream.

-
HWLOC_OBJ_BRIDGE_PCI 

PCI-side of a bridge.

-
- -
-
- -

◆ hwloc_obj_cache_type_e

- -
-
- - - - -
enum hwloc_obj_cache_type_e
-
- -

Cache type.

- - - - -
Enumerator
HWLOC_OBJ_CACHE_UNIFIED 

Unified cache.

-
HWLOC_OBJ_CACHE_DATA 

Data cache.

-
HWLOC_OBJ_CACHE_INSTRUCTION 

Instruction cache (filtered out by default).

-
- -
-
- -

◆ hwloc_obj_osdev_type_e

- -
-
- - - - -
enum hwloc_obj_osdev_type_e
-
- -

Type of a OS device.

- - - - - - - -
Enumerator
HWLOC_OBJ_OSDEV_BLOCK 

Operating system block device, or non-volatile memory device. For instance "sda" or "dax2.0" on Linux.

-
HWLOC_OBJ_OSDEV_GPU 

Operating system GPU device. For instance ":0.0" for a GL display, "card0" for a Linux DRM device.

-
HWLOC_OBJ_OSDEV_NETWORK 

Operating system network device. For instance the "eth0" interface on Linux.

-
HWLOC_OBJ_OSDEV_OPENFABRICS 

Operating system openfabrics device. For instance the "mlx4_0" InfiniBand HCA, "hfi1_0" Omni-Path interface, or "bxi0" Atos/Bull BXI HCA on Linux.

-
HWLOC_OBJ_OSDEV_DMA 

Operating system dma engine device. For instance the "dma0chan0" DMA channel on Linux.

-
HWLOC_OBJ_OSDEV_COPROC 

Operating system co-processor device. For instance "opencl0d0" for a OpenCL device, "cuda0" for a CUDA device.

-
- -
-
- -

◆ hwloc_obj_type_t

- -
-
- - - - -
enum hwloc_obj_type_t
-
- -

Type of topology object.

-
Note
Do not rely on the ordering or completeness of the values as new ones may be defined in the future! If you need to compare types, use hwloc_compare_types() instead.
- - - - - - - - - - - - - - - - - - - - - -
Enumerator
HWLOC_OBJ_MACHINE 

Machine. A set of processors and memory with cache coherency.

-

This type is always used for the root object of a topology, and never used anywhere else. Hence its parent is always NULL.

-
HWLOC_OBJ_PACKAGE 

Physical package. The physical package that usually gets inserted into a socket on the motherboard. A processor package usually contains multiple cores, and possibly some dies.

-
HWLOC_OBJ_CORE 

Core. A computation unit (may be shared by several PUs, aka logical processors).

-
HWLOC_OBJ_PU 

Processing Unit, or (Logical) Processor. An execution unit (may share a core with some other logical processors, e.g. in the case of an SMT core).

-

This is the smallest object representing CPU resources, it cannot have any child except Misc objects.

-

Objects of this kind are always reported and can thus be used as fallback when others are not.

-
HWLOC_OBJ_L1CACHE 

Level 1 Data (or Unified) Cache.

-
HWLOC_OBJ_L2CACHE 

Level 2 Data (or Unified) Cache.

-
HWLOC_OBJ_L3CACHE 

Level 3 Data (or Unified) Cache.

-
HWLOC_OBJ_L4CACHE 

Level 4 Data (or Unified) Cache.

-
HWLOC_OBJ_L5CACHE 

Level 5 Data (or Unified) Cache.

-
HWLOC_OBJ_L1ICACHE 

Level 1 instruction Cache (filtered out by default).

-
HWLOC_OBJ_L2ICACHE 

Level 2 instruction Cache (filtered out by default).

-
HWLOC_OBJ_L3ICACHE 

Level 3 instruction Cache (filtered out by default).

-
HWLOC_OBJ_GROUP 

Group objects. Objects which do not fit in the above but are detected by hwloc and are useful to take into account for affinity. For instance, some operating systems expose their arbitrary processors aggregation this way. And hwloc may insert such objects to group NUMA nodes according to their distances. See also What are these Group objects in my topology?.

-

These objects are removed when they do not bring any structure (see HWLOC_TYPE_FILTER_KEEP_STRUCTURE).

-
HWLOC_OBJ_NUMANODE 

NUMA node. An object that contains memory that is directly and byte-accessible to the host processors. It is usually close to some cores (the corresponding objects are descendants of the NUMA node object in the hwloc tree).

-

This is the smallest object representing Memory resources, it cannot have any child except Misc objects. However it may have Memory-side cache parents.

-

There is always at least one such object in the topology even if the machine is not NUMA.

-

Memory objects are not listed in the main children list, but rather in the dedicated Memory children list.

-

NUMA nodes have a special depth HWLOC_TYPE_DEPTH_NUMANODE instead of a normal depth just like other objects in the main tree.

-
HWLOC_OBJ_BRIDGE 

Bridge (filtered out by default). Any bridge (or PCI switch) that connects the host or an I/O bus, to another I/O bus.

-

Bridges are not added to the topology unless their filtering is changed (see hwloc_topology_set_type_filter() and hwloc_topology_set_io_types_filter()).

-

I/O objects are not listed in the main children list, but rather in the dedicated io children list. I/O objects have NULL CPU and node sets.

-
HWLOC_OBJ_PCI_DEVICE 

PCI device (filtered out by default).

-

PCI devices are not added to the topology unless their filtering is changed (see hwloc_topology_set_type_filter() and hwloc_topology_set_io_types_filter()).

-

I/O objects are not listed in the main children list, but rather in the dedicated io children list. I/O objects have NULL CPU and node sets.

-
HWLOC_OBJ_OS_DEVICE 

Operating system device (filtered out by default).

-

OS devices are not added to the topology unless their filtering is changed (see hwloc_topology_set_type_filter() and hwloc_topology_set_io_types_filter()).

-

I/O objects are not listed in the main children list, but rather in the dedicated io children list. I/O objects have NULL CPU and node sets.

-
HWLOC_OBJ_MISC 

Miscellaneous objects (filtered out by default). Objects without particular meaning, that can e.g. be added by the application for its own use, or by hwloc for miscellaneous objects such as MemoryModule (DIMMs).

-

They are not added to the topology unless their filtering is changed (see hwloc_topology_set_type_filter()).

-

These objects are not listed in the main children list, but rather in the dedicated misc children list. Misc objects may only have Misc objects as children, and those are in the dedicated misc children list as well. Misc objects have NULL CPU and node sets.

-
HWLOC_OBJ_MEMCACHE 

Memory-side cache (filtered out by default). A cache in front of a specific NUMA node.

-

This object always has at least one NUMA node as a memory child.

-

Memory objects are not listed in the main children list, but rather in the dedicated Memory children list.

-

Memory-side cache have a special depth HWLOC_TYPE_DEPTH_MEMCACHE instead of a normal depth just like other objects in the main tree.

-
HWLOC_OBJ_DIE 

Die within a physical package. A subpart of the physical package, that contains multiple cores.

-
- -
-
-

Function Documentation

- -

◆ hwloc_compare_types()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_compare_types (hwloc_obj_type_t type1,
hwloc_obj_type_t type2 
)
-
- -

Compare the depth of two object types.

-

Types shouldn't be compared as they are, since newer ones may be added in the future. This function returns less than, equal to, or greater than zero respectively if type1 objects usually include type2 objects, are the same as type2 objects, or are included in type2 objects. If the types can not be compared (because neither is usually contained in the other), HWLOC_TYPE_UNORDERED is returned. Object types containing CPUs can always be compared (usually, a system contains machines which contain nodes which contain packages which contain caches, which contain cores, which contain processors).

-
Note
HWLOC_OBJ_PU will always be the deepest, while HWLOC_OBJ_MACHINE is always the highest.
-
-This does not mean that the actual topology will respect that order: e.g. as of today cores may also contain caches, and packages may also contain nodes. This is thus just to be seen as a fallback comparison method.
- -
-
-
- - - - - - - -
-
-Data Structures | -Typedefs
-
-
Object Structure and Attributes
-
-
- - - - - - - - -

-Data Structures

struct  hwloc_obj
 
union  hwloc_obj_attr_u
 
struct  hwloc_info_s
 
- - - -

-Typedefs

typedef struct hwloc_obj * hwloc_obj_t
 
-

Detailed Description

-

Typedef Documentation

- -

◆ hwloc_obj_t

- -
-
- - - - -
typedef struct hwloc_obj* hwloc_obj_t
-
- -

Convenience typedef; a pointer to a struct hwloc_obj.

- -
-
-
- - - - - - - -
-
-Typedefs | -Functions
-
-
Topology Creation and Destruction
-
-
- - - - -

-Typedefs

typedef struct hwloc_topology * hwloc_topology_t
 
- - - - - - - - - - - - - -

-Functions

int hwloc_topology_init (hwloc_topology_t *topologyp)
 
int hwloc_topology_load (hwloc_topology_t topology)
 
void hwloc_topology_destroy (hwloc_topology_t topology)
 
int hwloc_topology_dup (hwloc_topology_t *newtopology, hwloc_topology_t oldtopology)
 
int hwloc_topology_abi_check (hwloc_topology_t topology)
 
void hwloc_topology_check (hwloc_topology_t topology)
 
-

Detailed Description

-

Typedef Documentation

- -

◆ hwloc_topology_t

- -
-
- - - - -
typedef struct hwloc_topology* hwloc_topology_t
-
- -

Topology context.

-

To be initialized with hwloc_topology_init() and built with hwloc_topology_load().

- -
-
-

Function Documentation

- -

◆ hwloc_topology_abi_check()

- -
-
- - - - - - - - -
int hwloc_topology_abi_check (hwloc_topology_t topology)
-
- -

Verify that the topology is compatible with the current hwloc library.

-

This is useful when using the same topology structure (in memory) in different libraries that may use different hwloc installations (for instance if one library embeds a specific version of hwloc, while another library uses a default system-wide hwloc installation).

-

If all libraries/programs use the same hwloc installation, this function always returns success.

-
Returns
0 on success.
-
--1 with errno set to EINVAL if incompatible.
-
Note
If sharing between processes with hwloc_shmem_topology_write(), the relevant check is already performed inside hwloc_shmem_topology_adopt().
- -
-
- -

◆ hwloc_topology_check()

- -
-
- - - - - - - - -
void hwloc_topology_check (hwloc_topology_t topology)
-
- -

Run internal checks on a topology structure.

-

The program aborts if an inconsistency is detected in the given topology.

-
Parameters
- - -
topologyis the topology to be checked
-
-
-
Note
This routine is only useful to developers.
-
-The input topology should have been previously loaded with hwloc_topology_load().
- -
-
- -

◆ hwloc_topology_destroy()

- -
-
- - - - - - - - -
void hwloc_topology_destroy (hwloc_topology_t topology)
-
- -

Terminate and free a topology context.

-
Parameters
- - -
topologyis the topology to be freed
-
-
- -
-
- -

◆ hwloc_topology_dup()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_topology_dup (hwloc_topology_t * newtopology,
hwloc_topology_t oldtopology 
)
-
- -

Duplicate a topology.

-

The entire topology structure as well as its objects are duplicated into a new one.

-

This is useful for keeping a backup while modifying a topology.

-
Note
Object userdata is not duplicated since hwloc does not know what it point to. The objects of both old and new topologies will point to the same userdata.
- -
-
- -

◆ hwloc_topology_init()

- -
-
- - - - - - - - -
int hwloc_topology_init (hwloc_topology_t * topologyp)
-
- -

Allocate a topology context.

-
Parameters
- - -
[out]topologypis assigned a pointer to the new allocated context.
-
-
-
Returns
0 on success, -1 on error.
- -
-
- -

◆ hwloc_topology_load()

- -
-
- - - - - - - - -
int hwloc_topology_load (hwloc_topology_t topology)
-
- -

Build the actual topology.

-

Build the actual topology once initialized with hwloc_topology_init() and tuned with Topology Detection Configuration and Query and Changing the Source of Topology Discovery routines. No other routine may be called earlier using this topology context.

-
Parameters
- - -
topologyis the topology to be loaded with objects.
-
-
-
Returns
0 on success, -1 on error.
-
Note
On failure, the topology is reinitialized. It should be either destroyed with hwloc_topology_destroy() or configured and loaded again.
-
-This function may be called only once per topology.
-
-The binding of the current thread or process may temporarily change during this call but it will be restored before it returns.
-
See also
Topology Detection Configuration and Query and Changing the Source of Topology Discovery
- -
-
-
- - - - - - - -
-
-Enumerations | -Functions
-
-
Object levels, depths and types
-
-
- - - - -

-Enumerations

enum  hwloc_get_type_depth_e {
-  HWLOC_TYPE_DEPTH_UNKNOWN -, HWLOC_TYPE_DEPTH_MULTIPLE -, HWLOC_TYPE_DEPTH_NUMANODE -, HWLOC_TYPE_DEPTH_BRIDGE -,
-  HWLOC_TYPE_DEPTH_PCI_DEVICE -, HWLOC_TYPE_DEPTH_OS_DEVICE -, HWLOC_TYPE_DEPTH_MISC -, HWLOC_TYPE_DEPTH_MEMCACHE -
- }
 
- - - - - - - - - - - - - - - - - - - - - - - - - - - -

-Functions

int hwloc_topology_get_depth (hwloc_topology_t restrict topology)
 
int hwloc_get_type_depth (hwloc_topology_t topology, hwloc_obj_type_t type)
 
int hwloc_get_memory_parents_depth (hwloc_topology_t topology)
 
static int hwloc_get_type_or_below_depth (hwloc_topology_t topology, hwloc_obj_type_t type)
 
static int hwloc_get_type_or_above_depth (hwloc_topology_t topology, hwloc_obj_type_t type)
 
hwloc_obj_type_t hwloc_get_depth_type (hwloc_topology_t topology, int depth)
 
unsigned hwloc_get_nbobjs_by_depth (hwloc_topology_t topology, int depth)
 
static int hwloc_get_nbobjs_by_type (hwloc_topology_t topology, hwloc_obj_type_t type)
 
static hwloc_obj_t hwloc_get_root_obj (hwloc_topology_t topology)
 
hwloc_obj_t hwloc_get_obj_by_depth (hwloc_topology_t topology, int depth, unsigned idx)
 
static hwloc_obj_t hwloc_get_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx)
 
static hwloc_obj_t hwloc_get_next_obj_by_depth (hwloc_topology_t topology, int depth, hwloc_obj_t prev)
 
static hwloc_obj_t hwloc_get_next_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, hwloc_obj_t prev)
 
-

Detailed Description

-

Be sure to see the figure in Terms and Definitions that shows a complete topology tree, including depths, child/sibling/cousin relationships, and an example of an asymmetric topology where one package has fewer caches than its peers.

-

Enumeration Type Documentation

- -

◆ hwloc_get_type_depth_e

- -
-
- - - - -
enum hwloc_get_type_depth_e
-
- - - - - - - - - -
Enumerator
HWLOC_TYPE_DEPTH_UNKNOWN 

No object of given type exists in the topology.

-
HWLOC_TYPE_DEPTH_MULTIPLE 

Objects of given type exist at different depth in the topology (only for Groups).

-
HWLOC_TYPE_DEPTH_NUMANODE 

Virtual depth for NUMA nodes.

-
HWLOC_TYPE_DEPTH_BRIDGE 

Virtual depth for bridge object level.

-
HWLOC_TYPE_DEPTH_PCI_DEVICE 

Virtual depth for PCI device object level.

-
HWLOC_TYPE_DEPTH_OS_DEVICE 

Virtual depth for software device object level.

-
HWLOC_TYPE_DEPTH_MISC 

Virtual depth for Misc object.

-
HWLOC_TYPE_DEPTH_MEMCACHE 

Virtual depth for MemCache object.

-
- -
-
-

Function Documentation

- -

◆ hwloc_get_depth_type()

- -
-
- - - - - - - - - - - - - - - - - - -
hwloc_obj_type_t hwloc_get_depth_type (hwloc_topology_t topology,
int depth 
)
-
- -

Returns the type of objects at depth depth.

-

depth should between 0 and hwloc_topology_get_depth()-1, or a virtual depth such as HWLOC_TYPE_DEPTH_NUMANODE.

-
Returns
(hwloc_obj_type_t)-1 if depth depth does not exist.
- -
-
- -

◆ hwloc_get_memory_parents_depth()

- -
-
- - - - - - - - -
int hwloc_get_memory_parents_depth (hwloc_topology_t topology)
-
- -

Return the depth of parents where memory objects are attached.

-

Memory objects have virtual negative depths because they are not part of the main CPU-side hierarchy of objects. This depth should not be compared with other level depths.

-

If all Memory objects are attached to Normal parents at the same depth, this parent depth may be compared to other as usual, for instance for knowing whether NUMA nodes is attached above or below Packages.

-
Returns
The depth of Normal parents of all memory children if all these parents have the same depth. For instance the depth of the Package level if all NUMA nodes are attached to Package objects.
-
-HWLOC_TYPE_DEPTH_MULTIPLE if Normal parents of all memory children do not have the same depth. For instance if some NUMA nodes are attached to Packages while others are attached to Groups.
- -
-
- -

◆ hwloc_get_nbobjs_by_depth()

- -
-
- - - - - - - - - - - - - - - - - - -
unsigned hwloc_get_nbobjs_by_depth (hwloc_topology_t topology,
int depth 
)
-
- -

Returns the width of level at depth depth.

- -
-
- -

◆ hwloc_get_nbobjs_by_type()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static int hwloc_get_nbobjs_by_type (hwloc_topology_t topology,
hwloc_obj_type_t type 
)
- 		-inlinestatic
-
- -

Returns the width of level type type.

-

If no object for that type exists, 0 is returned. If there are several levels with objects of that type, -1 is returned.

- -
-
- -

◆ hwloc_get_next_obj_by_depth()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_get_next_obj_by_depth (hwloc_topology_t topology,
int depth,
hwloc_obj_t prev 
)
- 		-inlinestatic
-
- -

Returns the next object at depth depth.

-

If prev is NULL, return the first object at depth depth.

- -
-
- -

◆ hwloc_get_next_obj_by_type()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_get_next_obj_by_type (hwloc_topology_t topology,
hwloc_obj_type_t type,
hwloc_obj_t prev 
)
- 		-inlinestatic
-
- -

Returns the next object of type type.

-

If prev is NULL, return the first object at type type. If there are multiple or no depth for given type, return NULL and let the caller fallback to hwloc_get_next_obj_by_depth().

- -
-
- -

◆ hwloc_get_obj_by_depth()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
hwloc_obj_t hwloc_get_obj_by_depth (hwloc_topology_t topology,
int depth,
unsigned idx 
)
-
- -

Returns the topology object at logical index idx from depth depth.

- -
-
- -

◆ hwloc_get_obj_by_type()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_get_obj_by_type (hwloc_topology_t topology,
hwloc_obj_type_t type,
unsigned idx 
)
- 		-inlinestatic
-
- -

Returns the topology object at logical index idx with type type.

-

If no object for that type exists, NULL is returned. If there are several levels with objects of that type (HWLOC_OBJ_GROUP), NULL is returned and the caller may fallback to hwloc_get_obj_by_depth().

- -
-
- -

◆ hwloc_get_root_obj()

- -
-
- - - - - -
- - - - - - - - -
static hwloc_obj_t hwloc_get_root_obj (hwloc_topology_t topology)
- 		-inlinestatic
-
- -

Returns the top-object of the topology-tree.

-

Its type is HWLOC_OBJ_MACHINE.

- -
-
- -

◆ hwloc_get_type_depth()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_get_type_depth (hwloc_topology_t topology,
hwloc_obj_type_t type 
)
-
- -

Returns the depth of objects of type type.

-

If no object of this type is present on the underlying architecture, or if the OS doesn't provide this kind of information, the function returns HWLOC_TYPE_DEPTH_UNKNOWN.

-

If type is absent but a similar type is acceptable, see also hwloc_get_type_or_below_depth() and hwloc_get_type_or_above_depth().

-

If HWLOC_OBJ_GROUP is given, the function may return HWLOC_TYPE_DEPTH_MULTIPLE if multiple levels of Groups exist.

-

If a NUMA node, I/O or Misc object type is given, the function returns a virtual value because these objects are stored in special levels that are not CPU-related. This virtual depth may be passed to other hwloc functions such as hwloc_get_obj_by_depth() but it should not be considered as an actual depth by the application. In particular, it should not be compared with any other object depth or with the entire topology depth.

See also
hwloc_get_memory_parents_depth().
-
-hwloc_type_sscanf_as_depth() for returning the depth of objects whose type is given as a string.
- -
-
- -

◆ hwloc_get_type_or_above_depth()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static int hwloc_get_type_or_above_depth (hwloc_topology_t topology,
hwloc_obj_type_t type 
)
- 		-inlinestatic
-
- -

Returns the depth of objects of type type or above.

-

If no object of this type is present on the underlying architecture, the function returns the depth of the first "present" object typically containing type.

-

This function is only meaningful for normal object types. If a memory, I/O or Misc object type is given, the corresponding virtual depth is always returned (see hwloc_get_type_depth()).

-

May return HWLOC_TYPE_DEPTH_MULTIPLE for HWLOC_OBJ_GROUP just like hwloc_get_type_depth().

- -
-
- -

◆ hwloc_get_type_or_below_depth()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static int hwloc_get_type_or_below_depth (hwloc_topology_t topology,
hwloc_obj_type_t type 
)
- 		-inlinestatic
-
- -

Returns the depth of objects of type type or below.

-

If no object of this type is present on the underlying architecture, the function returns the depth of the first "present" object typically found inside type.

-

This function is only meaningful for normal object types. If a memory, I/O or Misc object type is given, the corresponding virtual depth is always returned (see hwloc_get_type_depth()).

-

May return HWLOC_TYPE_DEPTH_MULTIPLE for HWLOC_OBJ_GROUP just like hwloc_get_type_depth().

- -
-
- -

◆ hwloc_topology_get_depth()

- -
-
- - - - - - - - -
int hwloc_topology_get_depth (hwloc_topology_t restrict topology)
-
- -

Get the depth of the hierarchical tree of objects.

-

This is the depth of HWLOC_OBJ_PU objects plus one.

-
Note
NUMA nodes, I/O and Misc objects are ignored when computing the depth of the tree (they are placed on special levels).
- -
-
-
- - - - - - - -
-
-Functions
-
-
Converting between Object Types and Attributes, and Strings
-
-
- - - - - - - - - - - - -

-Functions

const char * hwloc_obj_type_string (hwloc_obj_type_t type)
 
int hwloc_obj_type_snprintf (char *restrict string, size_t size, hwloc_obj_t obj, int verbose)
 
int hwloc_obj_attr_snprintf (char *restrict string, size_t size, hwloc_obj_t obj, const char *restrict separator, int verbose)
 
int hwloc_type_sscanf (const char *string, hwloc_obj_type_t *typep, union hwloc_obj_attr_u *attrp, size_t attrsize)
 
int hwloc_type_sscanf_as_depth (const char *string, hwloc_obj_type_t *typep, hwloc_topology_t topology, int *depthp)
 
-

Detailed Description

-

Function Documentation

- -

◆ hwloc_obj_attr_snprintf()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_obj_attr_snprintf (char *restrict string,
size_t size,
hwloc_obj_t obj,
const char *restrict separator,
int verbose 
)
-
- -

Stringify the attributes of a given topology object into a human-readable form.

-

Attribute values are separated by separator.

-

Only the major attributes are printed in non-verbose mode.

-

If size is 0, string may safely be NULL.

-
Returns
the number of characters that were actually written if not truncating, or that would have been written (not including the ending \0).
- -
-
- -

◆ hwloc_obj_type_snprintf()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_obj_type_snprintf (char *restrict string,
size_t size,
hwloc_obj_t obj,
int verbose 
)
-
- -

Stringify the type of a given topology object into a human-readable form.

-

Contrary to hwloc_obj_type_string(), this function includes object-specific attributes (such as the Group depth, the Bridge type, or OS device type) in the output, and it requires the caller to provide the output buffer.

-

The output is guaranteed to be the same for all objects of a same topology level.

-

If verbose is 1, longer type names are used, e.g. L1Cache instead of L1.

-

The output string may be parsed back by hwloc_type_sscanf().

-

If size is 0, string may safely be NULL.

-
Returns
the number of characters that were actually written if not truncating, or that would have been written (not including the ending \0).
- -
-
- -

◆ hwloc_obj_type_string()

- -
-
- - - - - - - - -
const char* hwloc_obj_type_string (hwloc_obj_type_t type)
-
- -

Return a constant stringified object type.

-

This function is the basic way to convert a generic type into a string. The output string may be parsed back by hwloc_type_sscanf().

-

hwloc_obj_type_snprintf() may return a more precise output for a specific object, but it requires the caller to provide the output buffer.

- -
-
- -

◆ hwloc_type_sscanf()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_type_sscanf (const char * string,
hwloc_obj_type_t * typep,
union hwloc_obj_attr_u * attrp,
size_t attrsize 
)
-
- -

Return an object type and attributes from a type string.

-

Convert strings such as "Package" or "L1iCache" into the corresponding types. Matching is case-insensitive, and only the first letters are actually required to match.

-

The matched object type is set in typep (which cannot be NULL).

-

Type-specific attributes, for instance Cache type, Cache depth, Group depth, Bridge type or OS Device type may be returned in attrp. Attributes that are not specified in the string (for instance "Group" without a depth, or "L2Cache" without a cache type) are set to -1.

-

attrp is only filled if not NULL and if its size specified in attrsize is large enough. It should be at least as large as union hwloc_obj_attr_u.

-
Returns
0 if a type was correctly identified, otherwise -1.
-
Note
This function is guaranteed to match any string returned by hwloc_obj_type_string() or hwloc_obj_type_snprintf().
-
-This is an extended version of the now deprecated hwloc_obj_type_sscanf().
- -
-
- -

◆ hwloc_type_sscanf_as_depth()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_type_sscanf_as_depth (const char * string,
hwloc_obj_type_t * typep,
hwloc_topology_t topology,
int * depthp 
)
-
- -

Return an object type and its level depth from a type string.

-

Convert strings such as "Package" or "L1iCache" into the corresponding types and return in depthp the depth of the corresponding level in the topology topology.

-

If no object of this type is present on the underlying architecture, HWLOC_TYPE_DEPTH_UNKNOWN is returned.

-

If multiple such levels exist (for instance if giving Group without any depth), the function may return HWLOC_TYPE_DEPTH_MULTIPLE instead.

-

The matched object type is set in typep if typep is non NULL.

-
Note
This function is similar to hwloc_type_sscanf() followed by hwloc_get_type_depth() but it also automatically disambiguates multiple group levels etc.
-
-This function is guaranteed to match any string returned by hwloc_obj_type_string() or hwloc_obj_type_snprintf().
- -
-
-
- - - - - - - -
-
-Functions
-
-
Consulting and Adding Key-Value Info Attributes
-
-
- - - - - - -

-Functions

static const char * hwloc_obj_get_info_by_name (hwloc_obj_t obj, const char *name)
 
int hwloc_obj_add_info (hwloc_obj_t obj, const char *name, const char *value)
 
-

Detailed Description

-

Function Documentation

- -

◆ hwloc_obj_add_info()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_obj_add_info (hwloc_obj_t obj,
const char * name,
const char * value 
)
-
- -

Add the given info name and value pair to the given object.

-

The info is appended to the existing info array even if another key with the same name already exists.

-

The input strings are copied before being added in the object infos.

-
Returns
0 on success, -1 on error.
-
Note
This function may be used to enforce object colors in the lstopo graphical output by using "lstopoStyle" as a name and "Background=#rrggbb" as a value. See CUSTOM COLORS in the lstopo(1) manpage for details.
-
-If value contains some non-printable characters, they will be dropped when exporting to XML, see hwloc_topology_export_xml() in hwloc/export.h.
- -
-
- -

◆ hwloc_obj_get_info_by_name()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static const char* hwloc_obj_get_info_by_name (hwloc_obj_t obj,
const char * name 
)
- 		-inlinestatic
-
- -

Search the given key name in object infos and return the corresponding value.

-

If multiple keys match the given name, only the first one is returned.

-
Returns
NULL if no such key exists.
- -
-
-
- - - - - - - -
-
-Enumerations | -Functions
-
-
CPU binding
-
-
- - - - -

-Enumerations

enum  hwloc_cpubind_flags_t { HWLOC_CPUBIND_PROCESS -, HWLOC_CPUBIND_THREAD -, HWLOC_CPUBIND_STRICT -, HWLOC_CPUBIND_NOMEMBIND - }
 
- - - - - - - - - - - - - - - - - -

-Functions

int hwloc_set_cpubind (hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags)
 
int hwloc_get_cpubind (hwloc_topology_t topology, hwloc_cpuset_t set, int flags)
 
int hwloc_set_proc_cpubind (hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_cpuset_t set, int flags)
 
int hwloc_get_proc_cpubind (hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags)
 
int hwloc_set_thread_cpubind (hwloc_topology_t topology, hwloc_thread_t thread, hwloc_const_cpuset_t set, int flags)
 
int hwloc_get_thread_cpubind (hwloc_topology_t topology, hwloc_thread_t thread, hwloc_cpuset_t set, int flags)
 
int hwloc_get_last_cpu_location (hwloc_topology_t topology, hwloc_cpuset_t set, int flags)
 
int hwloc_get_proc_last_cpu_location (hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags)
 
-

Detailed Description

-

Some operating systems only support binding threads or processes to a single PU. Others allow binding to larger sets such as entire Cores or Packages or even random sets of individual PUs. In such operating system, the scheduler is free to run the task on one of these PU, then migrate it to another PU, etc. It is often useful to call hwloc_bitmap_singlify() on the target CPU set before passing it to the binding function to avoid these expensive migrations. See the documentation of hwloc_bitmap_singlify() for details.

-

Some operating systems do not provide all hwloc-supported mechanisms to bind processes, threads, etc. hwloc_topology_get_support() may be used to query about the actual CPU binding support in the currently used operating system.

-

When the requested binding operation is not available and the HWLOC_CPUBIND_STRICT flag was passed, the function returns -1. errno is set to ENOSYS when it is not possible to bind the requested kind of object processes/threads. errno is set to EXDEV when the requested cpuset can not be enforced (e.g. some systems only allow one CPU, and some other systems only allow one NUMA node).

-

If HWLOC_CPUBIND_STRICT was not passed, the function may fail as well, or the operating system may use a slightly different operation (with side-effects, smaller binding set, etc.) when the requested operation is not exactly supported.

-

The most portable version that should be preferred over the others, whenever possible, is the following one which just binds the current program, assuming it is single-threaded:

-
hwloc_set_cpubind(topology, set, 0),
-
hwloc_set_cpubind
int hwloc_set_cpubind(hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags)
Bind current process or thread on CPUs given in physical bitmap set.
-

If the program may be multithreaded, the following one should be preferred to only bind the current thread:

-
hwloc_set_cpubind(topology, set, HWLOC_CPUBIND_THREAD),
-
HWLOC_CPUBIND_THREAD
@ HWLOC_CPUBIND_THREAD
Bind current thread of current process.
Definition: hwloc.h:1162
-
See also
Some example codes are available under doc/examples/ in the source tree.
-
Note
To unbind, just call the binding function with either a full cpuset or a cpuset equal to the system cpuset.
-
-On some operating systems, CPU binding may have effects on memory binding, see HWLOC_CPUBIND_NOMEMBIND
-
-Running lstopo --top or hwloc-ps can be a very convenient tool to check how binding actually happened.
-

Enumeration Type Documentation

- -

◆ hwloc_cpubind_flags_t

- -
-
- - - - -
enum hwloc_cpubind_flags_t
-
- -

Process/Thread binding flags.

-

These bit flags can be used to refine the binding policy.

-

The default (0) is to bind the current process, assumed to be single-threaded, in a non-strict way. This is the most portable way to bind as all operating systems usually provide it.

-
Note
Not all systems support all kinds of binding. See the "Detailed Description" section of CPU binding for a description of errors that can occur.
- - - - - -
Enumerator
HWLOC_CPUBIND_PROCESS 

Bind all threads of the current (possibly) multithreaded process.

-
HWLOC_CPUBIND_THREAD 

Bind current thread of current process.

-
HWLOC_CPUBIND_STRICT 

Request for strict binding from the OS.

-

By default, when the designated CPUs are all busy while other CPUs are idle, operating systems may execute the thread/process on those other CPUs instead of the designated CPUs, to let them progress anyway. Strict binding means that the thread/process will _never_ execute on other CPUs than the designated CPUs, even when those are busy with other tasks and other CPUs are idle.

-
Note
Depending on the operating system, strict binding may not be possible (e.g., the OS does not implement it) or not allowed (e.g., for an administrative reasons), and the function will fail in that case.
-

When retrieving the binding of a process, this flag checks whether all its threads actually have the same binding. If the flag is not given, the binding of each thread will be accumulated.

-
Note
This flag is meaningless when retrieving the binding of a thread.
-
HWLOC_CPUBIND_NOMEMBIND 

Avoid any effect on memory binding.

-

On some operating systems, some CPU binding function would also bind the memory on the corresponding NUMA node. It is often not a problem for the application, but if it is, setting this flag will make hwloc avoid using OS functions that would also bind memory. This will however reduce the support of CPU bindings, i.e. potentially return -1 with errno set to ENOSYS in some cases.

-

This flag is only meaningful when used with functions that set the CPU binding. It is ignored when used with functions that get CPU binding information.

-
- -
-
-

Function Documentation

- -

◆ hwloc_get_cpubind()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_get_cpubind (hwloc_topology_t topology,
hwloc_cpuset_t set,
int flags 
)
-
- -

Get current process or thread binding.

-

The CPU-set set (previously allocated by the caller) is filled with the list of PUs which the process or thread (according to flags) was last bound to.

- -
-
- -

◆ hwloc_get_last_cpu_location()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_get_last_cpu_location (hwloc_topology_t topology,
hwloc_cpuset_t set,
int flags 
)
-
- -

Get the last physical CPU where the current process or thread ran.

-

The CPU-set set (previously allocated by the caller) is filled with the list of PUs which the process or thread (according to flags) last ran on.

-

The operating system may move some tasks from one processor to another at any time according to their binding, so this function may return something that is already outdated.

-

flags can include either HWLOC_CPUBIND_PROCESS or HWLOC_CPUBIND_THREAD to specify whether the query should be for the whole process (union of all CPUs on which all threads are running), or only the current thread. If the process is single-threaded, flags can be set to zero to let hwloc use whichever method is available on the underlying OS.

- -
-
- -

◆ hwloc_get_proc_cpubind()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_get_proc_cpubind (hwloc_topology_t topology,
hwloc_pid_t pid,
hwloc_cpuset_t set,
int flags 
)
-
- -

Get the current physical binding of process pid.

-

The CPU-set set (previously allocated by the caller) is filled with the list of PUs which the process was last bound to.

-
Note
hwloc_pid_t is pid_t on Unix platforms, and HANDLE on native Windows platforms.
-
-As a special case on Linux, if a tid (thread ID) is supplied instead of a pid (process ID) and HWLOC_CPUBIND_THREAD is passed in flags, the binding for that specific thread is returned.
-
-On non-Linux systems, HWLOC_CPUBIND_THREAD can not be used in flags.
- -
-
- -

◆ hwloc_get_proc_last_cpu_location()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_get_proc_last_cpu_location (hwloc_topology_t topology,
hwloc_pid_t pid,
hwloc_cpuset_t set,
int flags 
)
-
- -

Get the last physical CPU where a process ran.

-

The CPU-set set (previously allocated by the caller) is filled with the list of PUs which the process last ran on.

-

The operating system may move some tasks from one processor to another at any time according to their binding, so this function may return something that is already outdated.

-
Note
hwloc_pid_t is pid_t on Unix platforms, and HANDLE on native Windows platforms.
-
-As a special case on Linux, if a tid (thread ID) is supplied instead of a pid (process ID) and HWLOC_CPUBIND_THREAD is passed in flags, the last CPU location of that specific thread is returned.
-
-On non-Linux systems, HWLOC_CPUBIND_THREAD can not be used in flags.
- -
-
- -

◆ hwloc_get_thread_cpubind()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_get_thread_cpubind (hwloc_topology_t topology,
hwloc_thread_t thread,
hwloc_cpuset_t set,
int flags 
)
-
- -

Get the current physical binding of thread tid.

-

The CPU-set set (previously allocated by the caller) is filled with the list of PUs which the thread was last bound to.

-
Note
hwloc_thread_t is pthread_t on Unix platforms, and HANDLE on native Windows platforms.
-
-HWLOC_CPUBIND_PROCESS can not be used in flags.
- -
-
- -

◆ hwloc_set_cpubind()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_set_cpubind (hwloc_topology_t topology,
hwloc_const_cpuset_t set,
int flags 
)
-
- -

Bind current process or thread on CPUs given in physical bitmap set.

-
Returns
-1 with errno set to ENOSYS if the action is not supported
-
--1 with errno set to EXDEV if the binding cannot be enforced
- -
-
- -

◆ hwloc_set_proc_cpubind()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_set_proc_cpubind (hwloc_topology_t topology,
hwloc_pid_t pid,
hwloc_const_cpuset_t set,
int flags 
)
-
- -

Bind a process pid on CPUs given in physical bitmap set.

-
Note
hwloc_pid_t is pid_t on Unix platforms, and HANDLE on native Windows platforms.
-
-As a special case on Linux, if a tid (thread ID) is supplied instead of a pid (process ID) and HWLOC_CPUBIND_THREAD is passed in flags, the binding is applied to that specific thread.
-
-On non-Linux systems, HWLOC_CPUBIND_THREAD can not be used in flags.
- -
-
- -

◆ hwloc_set_thread_cpubind()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_set_thread_cpubind (hwloc_topology_t topology,
hwloc_thread_t thread,
hwloc_const_cpuset_t set,
int flags 
)
-
- -

Bind a thread thread on CPUs given in physical bitmap set.

-
Note
hwloc_thread_t is pthread_t on Unix platforms, and HANDLE on native Windows platforms.
-
-HWLOC_CPUBIND_PROCESS can not be used in flags.
- -
-
-
- - - - - - - -
-
-Enumerations | -Functions
-
-
Memory binding
-
-
- - - - - - -

-Enumerations

enum  hwloc_membind_policy_t {
-  HWLOC_MEMBIND_DEFAULT -, HWLOC_MEMBIND_FIRSTTOUCH -, HWLOC_MEMBIND_BIND -, HWLOC_MEMBIND_INTERLEAVE -,
-  HWLOC_MEMBIND_NEXTTOUCH -, HWLOC_MEMBIND_MIXED -
- }
 
enum  hwloc_membind_flags_t {
-  HWLOC_MEMBIND_PROCESS -, HWLOC_MEMBIND_THREAD -, HWLOC_MEMBIND_STRICT -, HWLOC_MEMBIND_MIGRATE -,
-  HWLOC_MEMBIND_NOCPUBIND -, HWLOC_MEMBIND_BYNODESET -
- }
 
- - - - - - - - - - - - - - - - - - - - - - - -

-Functions

int hwloc_set_membind (hwloc_topology_t topology, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags)
 
int hwloc_get_membind (hwloc_topology_t topology, hwloc_bitmap_t set, hwloc_membind_policy_t *policy, int flags)
 
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)
 
int hwloc_get_proc_membind (hwloc_topology_t topology, hwloc_pid_t pid, hwloc_bitmap_t set, hwloc_membind_policy_t *policy, int flags)
 
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)
 
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)
 
int hwloc_get_area_memlocation (hwloc_topology_t topology, const void *addr, size_t len, hwloc_bitmap_t set, int flags)
 
void * hwloc_alloc (hwloc_topology_t topology, size_t len)
 
void * hwloc_alloc_membind (hwloc_topology_t topology, size_t len, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags)
 
static void * hwloc_alloc_membind_policy (hwloc_topology_t topology, size_t len, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags)
 
int hwloc_free (hwloc_topology_t topology, void *addr, size_t len)
 
-

Detailed Description

-

Memory binding can be done three ways:

- -

Not all operating systems support all three ways. hwloc_topology_get_support() may be used to query about the actual memory binding support in the currently used operating system.

-

When the requested binding operation is not available and the HWLOC_MEMBIND_STRICT flag was passed, the function returns -1. errno will be set to ENOSYS when the system does support the specified action or policy (e.g., some systems only allow binding memory on a per-thread basis, whereas other systems only allow binding memory for all threads in a process). errno will be set to EXDEV when the requested set can not be enforced (e.g., some systems only allow binding memory to a single NUMA node).

-

If HWLOC_MEMBIND_STRICT was not passed, the function may fail as well, or the operating system may use a slightly different operation (with side-effects, smaller binding set, etc.) when the requested operation is not exactly supported.

-

The most portable form that should be preferred over the others whenever possible is as follows. It allocates some memory hopefully bound to the specified set. To do so, hwloc will possibly have to change the current memory binding policy in order to actually get the memory bound, if the OS does not provide any other way to simply allocate bound memory without changing the policy for all allocations. That is the difference with hwloc_alloc_membind(), which will never change the current memory binding policy.

-
hwloc_alloc_membind_policy(topology, size, set,
-
HWLOC_MEMBIND_BIND, 0);
-
hwloc_alloc_membind_policy
static void * hwloc_alloc_membind_policy(hwloc_topology_t topology, size_t len, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags)
Allocate some memory on NUMA memory nodes specified by set.
-
HWLOC_MEMBIND_BIND
@ HWLOC_MEMBIND_BIND
Allocate memory on the specified nodes.
Definition: hwloc.h:1421
-

Each hwloc memory binding function takes a bitmap argument that is a CPU set by default, or a NUMA memory node set if the flag HWLOC_MEMBIND_BYNODESET is specified. See Object Sets (hwloc_cpuset_t and hwloc_nodeset_t) and The bitmap API for a discussion of CPU sets and NUMA memory node sets. It is also possible to convert between CPU set and node set using hwloc_cpuset_to_nodeset() or hwloc_cpuset_from_nodeset().

-

Memory binding by CPU set cannot work for CPU-less NUMA memory nodes. Binding by nodeset should therefore be preferred whenever possible.

-
See also
Some example codes are available under doc/examples/ in the source tree.
-
Note
On some operating systems, memory binding affects the CPU binding; see HWLOC_MEMBIND_NOCPUBIND
-

Enumeration Type Documentation

- -

◆ hwloc_membind_flags_t

- -
-
- - - - -
enum hwloc_membind_flags_t
-
- -

Memory binding flags.

-

These flags can be used to refine the binding policy. All flags can be logically OR'ed together with the exception of HWLOC_MEMBIND_PROCESS and HWLOC_MEMBIND_THREAD; these two flags are mutually exclusive.

-

Not all systems support all kinds of binding. hwloc_topology_get_support() may be used to query about the actual memory binding support in the currently used operating system. See the "Detailed Description" section of Memory binding for a description of errors that can occur.

- - - - - - - -
Enumerator
HWLOC_MEMBIND_PROCESS 

Set policy for all threads of the specified (possibly multithreaded) process. This flag is mutually exclusive with HWLOC_MEMBIND_THREAD.

-
HWLOC_MEMBIND_THREAD 

Set policy for a specific thread of the current process. This flag is mutually exclusive with HWLOC_MEMBIND_PROCESS.

-
HWLOC_MEMBIND_STRICT 

Request strict binding from the OS. The function will fail if the binding can not be guaranteed / completely enforced.

-

This flag has slightly different meanings depending on which function it is used with.

-
HWLOC_MEMBIND_MIGRATE 

Migrate existing allocated memory. If the memory cannot be migrated and the HWLOC_MEMBIND_STRICT flag is passed, an error will be returned.

-
HWLOC_MEMBIND_NOCPUBIND 

Avoid any effect on CPU binding.

-

On some operating systems, some underlying memory binding functions also bind the application to the corresponding CPU(s). Using this flag will cause hwloc to avoid using OS functions that could potentially affect CPU bindings. Note, however, that using NOCPUBIND may reduce hwloc's overall memory binding support. Specifically: some of hwloc's memory binding functions may fail with errno set to ENOSYS when used with NOCPUBIND.

-
HWLOC_MEMBIND_BYNODESET 

Consider the bitmap argument as a nodeset.

-

The bitmap argument is considered a nodeset if this flag is given, or a cpuset otherwise by default.

-

Memory binding by CPU set cannot work for CPU-less NUMA memory nodes. Binding by nodeset should therefore be preferred whenever possible.

-
- -
-
- -

◆ hwloc_membind_policy_t

- -
-
- - - - -
enum hwloc_membind_policy_t
-
- -

Memory binding policy.

-

These constants can be used to choose the binding policy. Only one policy can be used at a time (i.e., the values cannot be OR'ed together).

-

Not all systems support all kinds of binding. hwloc_topology_get_support() may be used to query about the actual memory binding policy support in the currently used operating system. See the "Detailed Description" section of Memory binding for a description of errors that can occur.

- - - - - - - -
Enumerator
HWLOC_MEMBIND_DEFAULT 

Reset the memory allocation policy to the system default. Depending on the operating system, this may correspond to HWLOC_MEMBIND_FIRSTTOUCH (Linux, FreeBSD), or HWLOC_MEMBIND_BIND (AIX, HP-UX, Solaris, Windows). This policy is never returned by get membind functions. The nodeset argument is ignored.

-
HWLOC_MEMBIND_FIRSTTOUCH 

Allocate each memory page individually on the local NUMA node of the thread that touches it.

-

The given nodeset should usually be hwloc_topology_get_topology_nodeset() so that the touching thread may run and allocate on any node in the system.

-

On AIX, if the nodeset is smaller, pages are allocated locally (if the local node is in the nodeset) or from a random non-local node (otherwise).

-
HWLOC_MEMBIND_BIND 

Allocate memory on the specified nodes.

-
HWLOC_MEMBIND_INTERLEAVE 

Allocate memory on the given nodes in an interleaved / round-robin manner. The precise layout of the memory across multiple NUMA nodes is OS/system specific. Interleaving can be useful when threads distributed across the specified NUMA nodes will all be accessing the whole memory range concurrently, since the interleave will then balance the memory references.

-
HWLOC_MEMBIND_NEXTTOUCH 

For each page bound with this policy, by next time it is touched (and next time only), it is moved from its current location to the local NUMA node of the thread where the memory reference occurred (if it needs to be moved at all).

-
HWLOC_MEMBIND_MIXED 

Returned by get_membind() functions when multiple threads or parts of a memory area have differing memory binding policies. Also returned when binding is unknown because binding hooks are empty when the topology is loaded from XML without HWLOC_THISSYSTEM=1, etc.

-
- -
-
-

Function Documentation

- -

◆ hwloc_alloc()

- -
-
- - - - - - - - - - - - - - - - - - -
void* hwloc_alloc (hwloc_topology_t topology,
size_t len 
)
-
- -

Allocate some memory.

-

This is equivalent to malloc(), except that it tries to allocate page-aligned memory from the OS.

-
Note
The allocated memory should be freed with hwloc_free().
- -
-
- -

◆ hwloc_alloc_membind()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
void* hwloc_alloc_membind (hwloc_topology_t topology,
size_t len,
hwloc_const_bitmap_t set,
hwloc_membind_policy_t policy,
int flags 
)
-
- -

Allocate some memory on NUMA memory nodes specified by set.

-
Returns
NULL with errno set to ENOSYS if the action is not supported and HWLOC_MEMBIND_STRICT is given
-
-NULL with errno set to EXDEV if the binding cannot be enforced and HWLOC_MEMBIND_STRICT is given
-
-NULL with errno set to ENOMEM if the memory allocation failed even before trying to bind.
-

If HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset. Otherwise it's a cpuset.

-
Note
The allocated memory should be freed with hwloc_free().
- -
-
- -

◆ hwloc_alloc_membind_policy()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
static void* hwloc_alloc_membind_policy (hwloc_topology_t topology,
size_t len,
hwloc_const_bitmap_t set,
hwloc_membind_policy_t policy,
int flags 
)
- 		-inlinestatic
-
- -

Allocate some memory on NUMA memory nodes specified by set.

-

First, try to allocate properly with hwloc_alloc_membind(). On failure, the current process or thread memory binding policy is changed with hwloc_set_membind() before allocating memory. Thus this function works in more cases, at the expense of changing the current state (possibly affecting future allocations that would not specify any policy).

-

If HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset. Otherwise it's a cpuset.

- -
-
- -

◆ hwloc_free()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_free (hwloc_topology_t topology,
void * addr,
size_t len 
)
-
- -

Free memory that was previously allocated by hwloc_alloc() or hwloc_alloc_membind().

- -
-
- -

◆ hwloc_get_area_membind()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
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 
)
-
- -

Query the CPUs near the physical NUMA node(s) and binding policy of the memory identified by (addr, len ).

-

The bitmap set (previously allocated by the caller) is filled with the memory area binding.

-

This function has two output parameters: set and policy. The values returned in these parameters depend on both the flags passed in and the memory binding policies and nodesets of the pages in the address range.

-

If HWLOC_MEMBIND_STRICT is specified, the target pages are first checked to see if they all have the same memory binding policy and nodeset. If they do not, -1 is returned and errno is set to EXDEV. If they are identical across all pages, the set and policy are returned in set and policy, respectively.

-

If HWLOC_MEMBIND_STRICT is not specified, the union of all NUMA node(s) containing pages in the address range is calculated. If all pages in the target have the same policy, it is returned in policy. Otherwise, policy is set to HWLOC_MEMBIND_MIXED.

-

If HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset. Otherwise it's a cpuset.

-

If any other flags are specified, -1 is returned and errno is set to EINVAL.

-

If len is 0, -1 is returned and errno is set to EINVAL.

- -
-
- -

◆ hwloc_get_area_memlocation()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_get_area_memlocation (hwloc_topology_t topology,
const void * addr,
size_t len,
hwloc_bitmap_t set,
int flags 
)
-
- -

Get the NUMA nodes where memory identified by (addr, len ) is physically allocated.

-

The bitmap set (previously allocated by the caller) is filled according to the NUMA nodes where the memory area pages are physically allocated. If no page is actually allocated yet, set may be empty.

-

If pages spread to multiple nodes, it is not specified whether they spread equitably, or whether most of them are on a single node, etc.

-

The operating system may move memory pages from one processor to another at any time according to their binding, so this function may return something that is already outdated.

-

If HWLOC_MEMBIND_BYNODESET is specified in flags, set is considered a nodeset. Otherwise it's a cpuset.

-

If len is 0, set is emptied.

- -
-
- -

◆ hwloc_get_membind()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_get_membind (hwloc_topology_t topology,
hwloc_bitmap_t set,
hwloc_membind_policy_t * policy,
int flags 
)
-
- -

Query the default memory binding policy and physical locality of the current process or thread.

-

The bitmap set (previously allocated by the caller) is filled with the process or thread memory binding.

-

This function has two output parameters: set and policy. The values returned in these parameters depend on both the flags passed in and the current memory binding policies and nodesets in the queried target.

-

Passing the HWLOC_MEMBIND_PROCESS flag specifies that the query target is the current policies and nodesets for all the threads in the current process. Passing HWLOC_MEMBIND_THREAD specifies that the query target is the current policy and nodeset for only the thread invoking this function.

-

If neither of these flags are passed (which is the most portable method), the process is assumed to be single threaded. This allows hwloc to use either process-based OS functions or thread-based OS functions, depending on which are available.

-

HWLOC_MEMBIND_STRICT is only meaningful when HWLOC_MEMBIND_PROCESS is also specified. In this case, hwloc will check the default memory policies and nodesets for all threads in the process. If they are not identical, -1 is returned and errno is set to EXDEV. If they are identical, the values are returned in set and policy.

-

Otherwise, if HWLOC_MEMBIND_PROCESS is specified (and HWLOC_MEMBIND_STRICT is not specified), the default set from each thread is logically OR'ed together. If all threads' default policies are the same, policy is set to that policy. If they are different, policy is set to HWLOC_MEMBIND_MIXED.

-

In the HWLOC_MEMBIND_THREAD case (or when neither HWLOC_MEMBIND_PROCESS or HWLOC_MEMBIND_THREAD is specified), there is only one set and policy; they are returned in set and policy, respectively.

-

If HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset. Otherwise it's a cpuset.

-

If any other flags are specified, -1 is returned and errno is set to EINVAL.

- -
-
- -

◆ hwloc_get_proc_membind()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_get_proc_membind (hwloc_topology_t topology,
hwloc_pid_t pid,
hwloc_bitmap_t set,
hwloc_membind_policy_t * policy,
int flags 
)
-
- -

Query the default memory binding policy and physical locality of the specified process.

-

The bitmap set (previously allocated by the caller) is filled with the process memory binding.

-

This function has two output parameters: set and policy. The values returned in these parameters depend on both the flags passed in and the current memory binding policies and nodesets in the queried target.

-

Passing the HWLOC_MEMBIND_PROCESS flag specifies that the query target is the current policies and nodesets for all the threads in the specified process. If HWLOC_MEMBIND_PROCESS is not specified (which is the most portable method), the process is assumed to be single threaded. This allows hwloc to use either process-based OS functions or thread-based OS functions, depending on which are available.

-

Note that it does not make sense to pass HWLOC_MEMBIND_THREAD to this function.

-

If HWLOC_MEMBIND_STRICT is specified, hwloc will check the default memory policies and nodesets for all threads in the specified process. If they are not identical, -1 is returned and errno is set to EXDEV. If they are identical, the values are returned in set and policy.

-

Otherwise, set is set to the logical OR of all threads' default set. If all threads' default policies are the same, policy is set to that policy. If they are different, policy is set to HWLOC_MEMBIND_MIXED.

-

If HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset. Otherwise it's a cpuset.

-

If any other flags are specified, -1 is returned and errno is set to EINVAL.

-
Note
hwloc_pid_t is pid_t on Unix platforms, and HANDLE on native Windows platforms.
- -
-
- -

◆ hwloc_set_area_membind()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
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 
)
-
- -

Bind the already-allocated memory identified by (addr, len) to the NUMA node(s) specified by set.

-

If HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset. Otherwise it's a cpuset.

-
Returns
0 if len is 0.
-
--1 with errno set to ENOSYS if the action is not supported
-
--1 with errno set to EXDEV if the binding cannot be enforced
- -
-
- -

◆ hwloc_set_membind()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_set_membind (hwloc_topology_t topology,
hwloc_const_bitmap_t set,
hwloc_membind_policy_t policy,
int flags 
)
-
- -

Set the default memory binding policy of the current process or thread to prefer the NUMA node(s) specified by set.

-

If neither HWLOC_MEMBIND_PROCESS nor HWLOC_MEMBIND_THREAD is specified, the current process is assumed to be single-threaded. This is the most portable form as it permits hwloc to use either process-based OS functions or thread-based OS functions, depending on which are available.

-

If HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset. Otherwise it's a cpuset.

-
Returns
-1 with errno set to ENOSYS if the action is not supported
-
--1 with errno set to EXDEV if the binding cannot be enforced
- -
-
- -

◆ hwloc_set_proc_membind()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
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 
)
-
- -

Set the default memory binding policy of the specified process to prefer the NUMA node(s) specified by set.

-

If HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset. Otherwise it's a cpuset.

-
Returns
-1 with errno set to ENOSYS if the action is not supported
-
--1 with errno set to EXDEV if the binding cannot be enforced
-
Note
hwloc_pid_t is pid_t on Unix platforms, and HANDLE on native Windows platforms.
- -
-
-
- - - - - - - -
-
-Enumerations | -Functions
-
-
Changing the Source of Topology Discovery
-
-
- - - - -

-Enumerations

enum  hwloc_topology_components_flag_e { HWLOC_TOPOLOGY_COMPONENTS_FLAG_BLACKLIST - }
 
- - - - - - - - - - - -

-Functions

int hwloc_topology_set_pid (hwloc_topology_t restrict topology, hwloc_pid_t pid)
 
int hwloc_topology_set_synthetic (hwloc_topology_t restrict topology, const char *restrict description)
 
int hwloc_topology_set_xml (hwloc_topology_t restrict topology, const char *restrict xmlpath)
 
int hwloc_topology_set_xmlbuffer (hwloc_topology_t restrict topology, const char *restrict buffer, int size)
 
int hwloc_topology_set_components (hwloc_topology_t restrict topology, unsigned long flags, const char *restrict name)
 
-

Detailed Description

-

If none of the functions below is called, the default is to detect all the objects of the machine that the caller is allowed to access.

-

This default behavior may also be modified through environment variables if the application did not modify it already. Setting HWLOC_XMLFILE in the environment enforces the discovery from a XML file as if hwloc_topology_set_xml() had been called. Setting HWLOC_SYNTHETIC enforces a synthetic topology as if hwloc_topology_set_synthetic() had been called.

-

Finally, HWLOC_THISSYSTEM enforces the return value of hwloc_topology_is_thissystem().

-

Enumeration Type Documentation

- -

◆ hwloc_topology_components_flag_e

- -
-
- - - - -
enum hwloc_topology_components_flag_e
-
- -

Flags to be passed to hwloc_topology_set_components()

- - -
Enumerator
HWLOC_TOPOLOGY_COMPONENTS_FLAG_BLACKLIST 

Blacklist the target component from being used.

-
- -
-
-

Function Documentation

- -

◆ hwloc_topology_set_components()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_topology_set_components (hwloc_topology_t restrict topology,
unsigned long flags,
const char *restrict name 
)
-
- -

Prevent a discovery component from being used for a topology.

-

name is the name of the discovery component that should not be used when loading topology topology. The name is a string such as "cuda".

-

For components with multiple phases, it may also be suffixed with the name of a phase, for instance "linux:io".

-

flags should be HWLOC_TOPOLOGY_COMPONENTS_FLAG_BLACKLIST.

-

This may be used to avoid expensive parts of the discovery process. For instance, CUDA-specific discovery may be expensive and unneeded while generic I/O discovery could still be useful.

- -
-
- -

◆ hwloc_topology_set_pid()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_topology_set_pid (hwloc_topology_t restrict topology,
hwloc_pid_t pid 
)
-
- -

Change which process the topology is viewed from.

-

On some systems, processes may have different views of the machine, for instance the set of allowed CPUs. By default, hwloc exposes the view from the current process. Calling hwloc_topology_set_pid() permits to make it expose the topology of the machine from the point of view of another process.

-
Note
hwloc_pid_t is pid_t on Unix platforms, and HANDLE on native Windows platforms.
-
--1 is returned and errno is set to ENOSYS on platforms that do not support this feature.
- -
-
- -

◆ hwloc_topology_set_synthetic()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_topology_set_synthetic (hwloc_topology_t restrict topology,
const char *restrict description 
)
-
- -

Enable synthetic topology.

-

Gather topology information from the given description, a space-separated string of <type:number> describing the object type and arity at each level. All types may be omitted (space-separated string of numbers) so that hwloc chooses all types according to usual topologies. See also the Synthetic topologies.

-

Setting the environment variable HWLOC_SYNTHETIC may also result in this behavior.

-

If description was properly parsed and describes a valid topology configuration, this function returns 0. Otherwise -1 is returned and errno is set to EINVAL.

-

Note that this function does not actually load topology information; it just tells hwloc where to load it from. You'll still need to invoke hwloc_topology_load() to actually load the topology information.

-
Note
For convenience, this backend provides empty binding hooks which just return success.
-
-On success, the synthetic component replaces the previously enabled component (if any), but the topology is not actually modified until hwloc_topology_load().
- -
-
- -

◆ hwloc_topology_set_xml()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_topology_set_xml (hwloc_topology_t restrict topology,
const char *restrict xmlpath 
)
-
- -

Enable XML-file based topology.

-

Gather topology information from the XML file given at xmlpath. Setting the environment variable HWLOC_XMLFILE may also result in this behavior. This file may have been generated earlier with hwloc_topology_export_xml() in hwloc/export.h, or lstopo file.xml.

-

Note that this function does not actually load topology information; it just tells hwloc where to load it from. You'll still need to invoke hwloc_topology_load() to actually load the topology information.

-
Returns
-1 with errno set to EINVAL on failure to read the XML file.
-
Note
See also hwloc_topology_set_userdata_import_callback() for importing application-specific object userdata.
-
-For convenience, this backend provides empty binding hooks which just return success. To have hwloc still actually call OS-specific hooks, the HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM has to be set to assert that the loaded file is really the underlying system.
-
-On success, the XML component replaces the previously enabled component (if any), but the topology is not actually modified until hwloc_topology_load().
- -
-
- -

◆ hwloc_topology_set_xmlbuffer()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_topology_set_xmlbuffer (hwloc_topology_t restrict topology,
const char *restrict buffer,
int size 
)
-
- -

Enable XML based topology using a memory buffer (instead of a file, as with hwloc_topology_set_xml()).

-

Gather topology information from the XML memory buffer given at buffer and of length size. This buffer may have been filled earlier with hwloc_topology_export_xmlbuffer() in hwloc/export.h.

-

Note that this function does not actually load topology information; it just tells hwloc where to load it from. You'll still need to invoke hwloc_topology_load() to actually load the topology information.

-
Returns
-1 with errno set to EINVAL on failure to read the XML buffer.
-
Note
See also hwloc_topology_set_userdata_import_callback() for importing application-specific object userdata.
-
-For convenience, this backend provides empty binding hooks which just return success. To have hwloc still actually call OS-specific hooks, the HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM has to be set to assert that the loaded file is really the underlying system.
-
-On success, the XML component replaces the previously enabled component (if any), but the topology is not actually modified until hwloc_topology_load().
- -
-
-
- - - - - - - -
-
-Data Structures | -Enumerations | -Functions
-
-
Topology Detection Configuration and Query
-
-
- - - - - - - - - - - - -

-Data Structures

struct  hwloc_topology_discovery_support
 
struct  hwloc_topology_cpubind_support
 
struct  hwloc_topology_membind_support
 
struct  hwloc_topology_misc_support
 
struct  hwloc_topology_support
 
- - - - - -

-Enumerations

enum  hwloc_topology_flags_e {
-  HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED -, HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM -, HWLOC_TOPOLOGY_FLAG_THISSYSTEM_ALLOWED_RESOURCES -, HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT = (1UL<<3) -,
-  HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_CPUBINDING = (1UL<<4) -, HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_MEMBINDING = (1UL<<5) -, HWLOC_TOPOLOGY_FLAG_DONT_CHANGE_BINDING = (1UL<<6) -, HWLOC_TOPOLOGY_FLAG_NO_DISTANCES = (1UL<<7) -,
-  HWLOC_TOPOLOGY_FLAG_NO_MEMATTRS = (1UL<<8) -, HWLOC_TOPOLOGY_FLAG_NO_CPUKINDS = (1UL<<9) -
- }
 
enum  hwloc_type_filter_e { HWLOC_TYPE_FILTER_KEEP_ALL -, HWLOC_TYPE_FILTER_KEEP_NONE -, HWLOC_TYPE_FILTER_KEEP_STRUCTURE -, HWLOC_TYPE_FILTER_KEEP_IMPORTANT - }
 
- - - - - - - - - - - - - - - - - - - - - - - - - -

-Functions

int hwloc_topology_set_flags (hwloc_topology_t topology, unsigned long flags)
 
unsigned long hwloc_topology_get_flags (hwloc_topology_t topology)
 
int hwloc_topology_is_thissystem (hwloc_topology_t restrict topology)
 
const struct hwloc_topology_support * hwloc_topology_get_support (hwloc_topology_t restrict topology)
 
int hwloc_topology_set_type_filter (hwloc_topology_t topology, hwloc_obj_type_t type, enum hwloc_type_filter_e filter)
 
int hwloc_topology_get_type_filter (hwloc_topology_t topology, hwloc_obj_type_t type, enum hwloc_type_filter_e *filter)
 
int hwloc_topology_set_all_types_filter (hwloc_topology_t topology, enum hwloc_type_filter_e filter)
 
int hwloc_topology_set_cache_types_filter (hwloc_topology_t topology, enum hwloc_type_filter_e filter)
 
int hwloc_topology_set_icache_types_filter (hwloc_topology_t topology, enum hwloc_type_filter_e filter)
 
int hwloc_topology_set_io_types_filter (hwloc_topology_t topology, enum hwloc_type_filter_e filter)
 
void hwloc_topology_set_userdata (hwloc_topology_t topology, const void *userdata)
 
void * hwloc_topology_get_userdata (hwloc_topology_t topology)
 
-

Detailed Description

-

Several functions can optionally be called between hwloc_topology_init() and hwloc_topology_load() to configure how the detection should be performed, e.g. to ignore some objects types, define a synthetic topology, etc.

-

Enumeration Type Documentation

- -

◆ hwloc_topology_flags_e

- -
-
- - - - -
enum hwloc_topology_flags_e
-
- -

Flags to be set onto a topology context before load.

-

Flags should be given to hwloc_topology_set_flags(). They may also be returned by hwloc_topology_get_flags().

- - - - - - - - - - - -
Enumerator
HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED 

Detect the whole system, ignore reservations, include disallowed objects.

-

Gather all online resources, even if some were disabled by the administrator. For instance, ignore Linux Cgroup/Cpusets and gather all processors and memory nodes. However offline PUs and NUMA nodes are still ignored.

-

When this flag is not set, PUs and NUMA nodes that are disallowed are not added to the topology. Parent objects (package, core, cache, etc.) are added only if some of their children are allowed. All existing PUs and NUMA nodes in the topology are allowed. hwloc_topology_get_allowed_cpuset() and hwloc_topology_get_allowed_nodeset() are equal to the root object cpuset and nodeset.

-

When this flag is set, the actual sets of allowed PUs and NUMA nodes are given by hwloc_topology_get_allowed_cpuset() and hwloc_topology_get_allowed_nodeset(). They may be smaller than the root object cpuset and nodeset.

-

If the current topology is exported to XML and reimported later, this flag should be set again in the reimported topology so that disallowed resources are reimported as well.

-
HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM 

Assume that the selected backend provides the topology for the system on which we are running.

-

This forces hwloc_topology_is_thissystem() to return 1, i.e. makes hwloc assume that the selected backend provides the topology for the system on which we are running, even if it is not the OS-specific backend but the XML backend for instance. This means making the binding functions actually call the OS-specific system calls and really do binding, while the XML backend would otherwise provide empty hooks just returning success.

-

Setting the environment variable HWLOC_THISSYSTEM may also result in the same behavior.

-

This can be used for efficiency reasons to first detect the topology once, save it to an XML file, and quickly reload it later through the XML backend, but still having binding functions actually do bind.

-
HWLOC_TOPOLOGY_FLAG_THISSYSTEM_ALLOWED_RESOURCES 

Get the set of allowed resources from the local operating system even if the topology was loaded from XML or synthetic description.

-

If the topology was loaded from XML or from a synthetic string, restrict it by applying the current process restrictions such as Linux Cgroup/Cpuset.

-

This is useful when the topology is not loaded directly from the local machine (e.g. for performance reason) and it comes with all resources, while the running process is restricted to only parts of the machine.

-

This flag is ignored unless HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM is also set since the loaded topology must match the underlying machine where restrictions will be gathered from.

-

Setting the environment variable HWLOC_THISSYSTEM_ALLOWED_RESOURCES would result in the same behavior.

-
HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT 

Import support from the imported topology.

-

When importing a XML topology from a remote machine, binding is disabled by default (see HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM). This disabling is also marked by putting zeroes in the corresponding supported feature bits reported by hwloc_topology_get_support().

-

The flag HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT actually imports support bits from the remote machine. It also sets the flag imported_support in the struct hwloc_topology_misc_support array. If the imported XML did not contain any support information (exporter hwloc is too old), this flag is not set.

-

Note that these supported features are only relevant for the hwloc installation that actually exported the XML topology (it may vary with the operating system, or with how hwloc was compiled).

-

Note that setting this flag however does not enable binding for the locally imported hwloc topology, it only reports what the remote hwloc and machine support.

-
HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_CPUBINDING 

Do not consider resources outside of the process CPU binding.

-

If the binding of the process is limited to a subset of cores, ignore the other cores during discovery.

-

The resulting topology is identical to what a call to hwloc_topology_restrict() would generate, but this flag also prevents hwloc from ever touching other resources during the discovery.

-

This flag especially tells the x86 backend to never temporarily rebind a thread on any excluded core. This is useful on Windows because such temporary rebinding can change the process binding. Another use-case is to avoid cores that would not be able to perform the hwloc discovery anytime soon because they are busy executing some high-priority real-time tasks.

-

If process CPU binding is not supported, the thread CPU binding is considered instead if supported, or the flag is ignored.

-

This flag requires HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM as well since binding support is required.

-
HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_MEMBINDING 

Do not consider resources outside of the process memory binding.

-

If the binding of the process is limited to a subset of NUMA nodes, ignore the other NUMA nodes during discovery.

-

The resulting topology is identical to what a call to hwloc_topology_restrict() would generate, but this flag also prevents hwloc from ever touching other resources during the discovery.

-

This flag is meant to be used together with HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_CPUBINDING when both cores and NUMA nodes should be ignored outside of the process binding.

-

If process memory binding is not supported, the thread memory binding is considered instead if supported, or the flag is ignored.

-

This flag requires HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM as well since binding support is required.

-
HWLOC_TOPOLOGY_FLAG_DONT_CHANGE_BINDING 

Do not ever modify the process or thread binding during discovery.

-

This flag disables all hwloc discovery steps that require a change of the process or thread binding. This currently only affects the x86 backend which gets entirely disabled.

-

This is useful when hwloc_topology_load() is called while the application also creates additional threads or modifies the binding.

-

This flag is also a strict way to make sure the process binding will not change to due thread binding changes on Windows (see HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_CPUBINDING).

-
HWLOC_TOPOLOGY_FLAG_NO_DISTANCES 

Ignore distances.

-

Ignore distance information from the operating systems (and from XML) and hence do not use distances for grouping.

-
HWLOC_TOPOLOGY_FLAG_NO_MEMATTRS 

Ignore memory attributes.

-

Ignore memory attribues from the operating systems (and from XML).

-
HWLOC_TOPOLOGY_FLAG_NO_CPUKINDS 

Ignore CPU Kinds.

-

Ignore CPU kind information from the operating systems (and from XML).

-
- -
-
- -

◆ hwloc_type_filter_e

- -
-
- - - - -
enum hwloc_type_filter_e
-
- -

Type filtering flags.

-

By default, most objects are kept (HWLOC_TYPE_FILTER_KEEP_ALL). Instruction caches, I/O and Misc objects are ignored by default (HWLOC_TYPE_FILTER_KEEP_NONE). Die and Group levels are ignored unless they bring structure (HWLOC_TYPE_FILTER_KEEP_STRUCTURE).

-

Note that group objects are also ignored individually (without the entire level) when they do not bring structure.

- - - - - -
Enumerator
HWLOC_TYPE_FILTER_KEEP_ALL 

Keep all objects of this type.

-

Cannot be set for HWLOC_OBJ_GROUP (groups are designed only to add more structure to the topology).

-
HWLOC_TYPE_FILTER_KEEP_NONE 

Ignore all objects of this type.

-

The bottom-level type HWLOC_OBJ_PU, the HWLOC_OBJ_NUMANODE type, and the top-level type HWLOC_OBJ_MACHINE may not be ignored.

-
HWLOC_TYPE_FILTER_KEEP_STRUCTURE 

Only ignore objects if their entire level does not bring any structure.

-

Keep the entire level of objects if at least one of these objects adds structure to the topology. An object brings structure when it has multiple children and it is not the only child of its parent.

-

If all objects in the level are the only child of their parent, and if none of them has multiple children, the entire level is removed.

-

Cannot be set for I/O and Misc objects since the topology structure does not matter there.

-
HWLOC_TYPE_FILTER_KEEP_IMPORTANT 

Only keep likely-important objects of the given type.

-

It is only useful for I/O object types. For HWLOC_OBJ_PCI_DEVICE and HWLOC_OBJ_OS_DEVICE, it means that only objects of major/common kinds are kept (storage, network, OpenFabrics, CUDA, OpenCL, RSMI, NVML, and displays). Also, only OS devices directly attached on PCI (e.g. no USB) are reported. For HWLOC_OBJ_BRIDGE, it means that bridges are kept only if they have children.

-

This flag equivalent to HWLOC_TYPE_FILTER_KEEP_ALL for Normal, Memory and Misc types since they are likely important.

-
- -
-
-

Function Documentation

- -

◆ hwloc_topology_get_flags()

- -
-
- - - - - - - - -
unsigned long hwloc_topology_get_flags (hwloc_topology_t topology)
-
- -

Get OR'ed flags of a topology.

-

Get the OR'ed set of hwloc_topology_flags_e of a topology.

-

If hwloc_topology_set_flags() was not called earlier, no flags are set (0 is returned).

-
Returns
the flags previously set with hwloc_topology_set_flags().
- -
-
- -

◆ hwloc_topology_get_support()

- -
-
- - - - - - - - -
const struct hwloc_topology_support* hwloc_topology_get_support (hwloc_topology_t restrict topology)
-
- -

Retrieve the topology support.

-

Each flag indicates whether a feature is supported. If set to 0, the feature is not supported. If set to 1, the feature is supported, but the corresponding call may still fail in some corner cases.

-

These features are also listed by hwloc-info --support

-

The reported features are what the current topology supports on the current machine. If the topology was exported to XML from another machine and later imported here, support still describes what is supported for this imported topology after import. By default, binding will be reported as unsupported in this case (see HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM).

-

Topology flag HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT may be used to report the supported features of the original remote machine instead. If it was successfully imported, imported_support will be set in the struct hwloc_topology_misc_support array.

- -
-
- -

◆ hwloc_topology_get_type_filter()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_topology_get_type_filter (hwloc_topology_t topology,
hwloc_obj_type_t type,
enum hwloc_type_filter_e * filter 
)
-
- -

Get the current filtering for the given object type.

- -
-
- -

◆ hwloc_topology_get_userdata()

- -
-
- - - - - - - - -
void* hwloc_topology_get_userdata (hwloc_topology_t topology)
-
- -

Retrieve the topology-specific userdata pointer.

-

Retrieve the application-given private data pointer that was previously set with hwloc_topology_set_userdata().

- -
-
- -

◆ hwloc_topology_is_thissystem()

- -
-
- - - - - - - - -
int hwloc_topology_is_thissystem (hwloc_topology_t restrict topology)
-
- -

Does the topology context come from this system?

-
Returns
1 if this topology context was built using the system running this program.
-
-0 instead (for instance if using another file-system root, a XML topology file, or a synthetic topology).
- -
-
- -

◆ hwloc_topology_set_all_types_filter()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_topology_set_all_types_filter (hwloc_topology_t topology,
enum hwloc_type_filter_e filter 
)
-
- -

Set the filtering for all object types.

-

If some types do not support this filtering, they are silently ignored.

- -
-
- -

◆ hwloc_topology_set_cache_types_filter()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_topology_set_cache_types_filter (hwloc_topology_t topology,
enum hwloc_type_filter_e filter 
)
-
- -

Set the filtering for all CPU cache object types.

-

Memory-side caches are not involved since they are not CPU caches.

- -
-
- -

◆ hwloc_topology_set_flags()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_topology_set_flags (hwloc_topology_t topology,
unsigned long flags 
)
-
- -

Set OR'ed flags to non-yet-loaded topology.

-

Set a OR'ed set of hwloc_topology_flags_e onto a topology that was not yet loaded.

-

If this function is called multiple times, the last invocation will erase and replace the set of flags that was previously set.

-

By default, no flags are set (0).

-

The flags set in a topology may be retrieved with hwloc_topology_get_flags().

- -
-
- -

◆ hwloc_topology_set_icache_types_filter()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_topology_set_icache_types_filter (hwloc_topology_t topology,
enum hwloc_type_filter_e filter 
)
-
- -

Set the filtering for all CPU instruction cache object types.

-

Memory-side caches are not involved since they are not CPU caches.

- -
-
- -

◆ hwloc_topology_set_io_types_filter()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_topology_set_io_types_filter (hwloc_topology_t topology,
enum hwloc_type_filter_e filter 
)
-
- -

Set the filtering for all I/O object types.

- -
-
- -

◆ hwloc_topology_set_type_filter()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_topology_set_type_filter (hwloc_topology_t topology,
hwloc_obj_type_t type,
enum hwloc_type_filter_e filter 
)
-
- -

Set the filtering for the given object type.

- -
-
- -

◆ hwloc_topology_set_userdata()

- -
-
- - - - - - - - - - - - - - - - - - -
void hwloc_topology_set_userdata (hwloc_topology_t topology,
const void * userdata 
)
-
- -

Set the topology-specific userdata pointer.

-

Each topology may store one application-given private data pointer. It is initialized to NULL. hwloc will never modify it.

-

Use it as you wish, after hwloc_topology_init() and until hwloc_topolog_destroy().

-

This pointer is not exported to XML.

- -
-
-
- - - - - - - -
-
-Enumerations | -Functions
-
-
Modifying a loaded Topology
-
-
- - - - - - -

-Enumerations

enum  hwloc_restrict_flags_e {
-  HWLOC_RESTRICT_FLAG_REMOVE_CPULESS -, HWLOC_RESTRICT_FLAG_BYNODESET = (1UL<<3) -, HWLOC_RESTRICT_FLAG_REMOVE_MEMLESS -, HWLOC_RESTRICT_FLAG_ADAPT_MISC -,
-  HWLOC_RESTRICT_FLAG_ADAPT_IO -
- }
 
enum  hwloc_allow_flags_e { HWLOC_ALLOW_FLAG_ALL -, HWLOC_ALLOW_FLAG_LOCAL_RESTRICTIONS -, HWLOC_ALLOW_FLAG_CUSTOM - }
 
- - - - - - - - - - - - - - - -

-Functions

int hwloc_topology_restrict (hwloc_topology_t restrict topology, hwloc_const_bitmap_t set, unsigned long flags)
 
int hwloc_topology_allow (hwloc_topology_t restrict topology, hwloc_const_cpuset_t cpuset, hwloc_const_nodeset_t nodeset, unsigned long flags)
 
hwloc_obj_t hwloc_topology_insert_misc_object (hwloc_topology_t topology, hwloc_obj_t parent, const char *name)
 
hwloc_obj_t hwloc_topology_alloc_group_object (hwloc_topology_t topology)
 
hwloc_obj_t hwloc_topology_insert_group_object (hwloc_topology_t topology, hwloc_obj_t group)
 
int hwloc_obj_add_other_obj_sets (hwloc_obj_t dst, hwloc_obj_t src)
 
int hwloc_topology_refresh (hwloc_topology_t topology)
 
-

Detailed Description

-

Enumeration Type Documentation

- -

◆ hwloc_allow_flags_e

- -
-
- - - - -
enum hwloc_allow_flags_e
-
- -

Flags to be given to hwloc_topology_allow().

- - - - -
Enumerator
HWLOC_ALLOW_FLAG_ALL 

Mark all objects as allowed in the topology.

-

cpuset and nođeset given to hwloc_topology_allow() must be NULL.

-
HWLOC_ALLOW_FLAG_LOCAL_RESTRICTIONS 

Only allow objects that are available to the current process.

-

The topology must have HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM so that the set of available resources can actually be retrieved from the operating system.

-

cpuset and nođeset given to hwloc_topology_allow() must be NULL.

-
HWLOC_ALLOW_FLAG_CUSTOM 

Allow a custom set of objects, given to hwloc_topology_allow() as cpuset and/or nodeset parameters.

-
- -
-
- -

◆ hwloc_restrict_flags_e

- -
-
- - - - -
enum hwloc_restrict_flags_e
-
- -

Flags to be given to hwloc_topology_restrict().

- - - - - - -
Enumerator
HWLOC_RESTRICT_FLAG_REMOVE_CPULESS 

Remove all objects that became CPU-less. By default, only objects that contain no PU and no memory are removed. This flag may not be used with HWLOC_RESTRICT_FLAG_BYNODESET.

-
HWLOC_RESTRICT_FLAG_BYNODESET 

Restrict by nodeset instead of CPU set. Only keep objects whose nodeset is included or partially included in the given set. This flag may not be used with HWLOC_RESTRICT_FLAG_REMOVE_CPULESS.

-
HWLOC_RESTRICT_FLAG_REMOVE_MEMLESS 

Remove all objects that became Memory-less. By default, only objects that contain no PU and no memory are removed. This flag may only be used with HWLOC_RESTRICT_FLAG_BYNODESET.

-
HWLOC_RESTRICT_FLAG_ADAPT_MISC 

Move Misc objects to ancestors if their parents are removed during restriction. If this flag is not set, Misc objects are removed when their parents are removed.

-
HWLOC_RESTRICT_FLAG_ADAPT_IO 

Move I/O objects to ancestors if their parents are removed during restriction. If this flag is not set, I/O devices and bridges are removed when their parents are removed.

-
- -
-
-

Function Documentation

- -

◆ hwloc_obj_add_other_obj_sets()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_obj_add_other_obj_sets (hwloc_obj_t dst,
hwloc_obj_t src 
)
-
- -

Setup object cpusets/nodesets by OR'ing another object's sets.

-

For each defined cpuset or nodeset in src, allocate the corresponding set in dst and add src to it by OR'ing sets.

-

This function is convenient between hwloc_topology_alloc_group_object() and hwloc_topology_insert_group_object(). It builds the sets of the new Group that will be inserted as a new intermediate parent of several objects.

- -
-
- -

◆ hwloc_topology_alloc_group_object()

- -
-
- - - - - - - - -
hwloc_obj_t hwloc_topology_alloc_group_object (hwloc_topology_t topology)
-
- -

Allocate a Group object to insert later with hwloc_topology_insert_group_object().

-

This function returns a new Group object.

-

The caller should (at least) initialize its sets before inserting the object in the topology. See hwloc_topology_insert_group_object().

- -
-
- -

◆ hwloc_topology_allow()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_topology_allow (hwloc_topology_t restrict topology,
hwloc_const_cpuset_t cpuset,
hwloc_const_nodeset_t nodeset,
unsigned long flags 
)
-
- -

Change the sets of allowed PUs and NUMA nodes in the topology.

-

This function only works if the HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED was set on the topology. It does not modify any object, it only changes the sets returned by hwloc_topology_get_allowed_cpuset() and hwloc_topology_get_allowed_nodeset().

-

It is notably useful when importing a topology from another process running in a different Linux Cgroup.

-

flags must be set to one flag among hwloc_allow_flags_e.

-
Note
Removing objects from a topology should rather be performed with hwloc_topology_restrict().
- -
-
- -

◆ hwloc_topology_insert_group_object()

- -
-
- - - - - - - - - - - - - - - - - - -
hwloc_obj_t hwloc_topology_insert_group_object (hwloc_topology_t topology,
hwloc_obj_t group 
)
-
- -

Add more structure to the topology by adding an intermediate Group.

-

The caller should first allocate a new Group object with hwloc_topology_alloc_group_object(). Then it must setup at least one of its CPU or node sets to specify the final location of the Group in the topology. Then the object can be passed to this function for actual insertion in the topology.

-

Either the cpuset or nodeset field (or both, if compatible) must be set to a non-empty bitmap. The complete_cpuset or complete_nodeset may be set instead if inserting with respect to the complete topology (including disallowed, offline or unknown objects). If grouping several objects, hwloc_obj_add_other_obj_sets() is an easy way to build the Group sets iteratively. These sets cannot be larger than the current topology, or they would get restricted silently. The core will setup the other sets after actual insertion.

-

The subtype object attribute may be defined (to a dynamically allocated string) to display something else than "Group" as the type name for this object in lstopo. Custom name/value info pairs may be added with hwloc_obj_add_info() after insertion.

-

The group dont_merge attribute may be set to 1 to prevent the hwloc core from ever merging this object with another hierarchically-identical object. This is useful when the Group itself describes an important feature that cannot be exposed anywhere else in the hierarchy.

-

The group kind attribute may be set to a high value such as 0xffffffff to tell hwloc that this new Group should always be discarded in favor of any existing Group with the same locality.

-
Returns
The inserted object if it was properly inserted.
-
-An existing object if the Group was merged or discarded because the topology already contained an object at the same location (the Group did not add any hierarchy information).
-
-NULL if the insertion failed because of conflicting sets in topology tree.
-
-NULL if Group objects are filtered-out of the topology (HWLOC_TYPE_FILTER_KEEP_NONE).
-
-NULL if the object was discarded because no set was initialized in the Group before insert, or all of them were empty.
- -
-
- -

◆ hwloc_topology_insert_misc_object()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
hwloc_obj_t hwloc_topology_insert_misc_object (hwloc_topology_t topology,
hwloc_obj_t parent,
const char * name 
)
-
- -

Add a MISC object as a leaf of the topology.

-

A new MISC object will be created and inserted into the topology at the position given by parent. It is appended to the list of existing Misc children, without ever adding any intermediate hierarchy level. This is useful for annotating the topology without actually changing the hierarchy.

-

name is supposed to be unique across all Misc objects in the topology. It will be duplicated to setup the new object attributes.

-

The new leaf object will not have any cpuset.

-
Returns
the newly-created object
-
-NULL on error.
-
-NULL if Misc objects are filtered-out of the topology (HWLOC_TYPE_FILTER_KEEP_NONE).
-
Note
If name contains some non-printable characters, they will be dropped when exporting to XML, see hwloc_topology_export_xml() in hwloc/export.h.
- -
-
- -

◆ hwloc_topology_refresh()

- -
-
- - - - - - - - -
int hwloc_topology_refresh (hwloc_topology_t topology)
-
- -

Refresh internal structures after topology modification.

-

Modifying the topology (by restricting, adding objects, modifying structures such as distances or memory attributes, etc.) may cause some internal caches to become invalid. These caches are automatically refreshed when accessed but this refreshing is not thread-safe.

-

This function is not thread-safe either, but it is a good way to end a non-thread-safe phase of topology modification. Once this refresh is done, multiple threads may concurrently consult the topology, objects, distances, attributes, etc.

-

See also Thread Safety

- -
-
- -

◆ hwloc_topology_restrict()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_topology_restrict (hwloc_topology_t restrict topology,
hwloc_const_bitmap_t set,
unsigned long flags 
)
-
- -

Restrict the topology to the given CPU set or nodeset.

-

Topology topology is modified so as to remove all objects that are not included (or partially included) in the CPU set set. All objects CPU and node sets are restricted accordingly.

-

If HWLOC_RESTRICT_FLAG_BYNODESET is passed in flags, set is considered a nodeset instead of a CPU set.

-

flags is a OR'ed set of hwloc_restrict_flags_e.

-
Note
This call may not be reverted by restricting back to a larger set. Once dropped during restriction, objects may not be brought back, except by loading another topology with hwloc_topology_load().
-
Returns
0 on success.
-
--1 with errno set to EINVAL if the input set is invalid. The topology is not modified in this case.
-
--1 with errno set to ENOMEM on failure to allocate internal data. The topology is reinitialized in this case. It should be either destroyed with hwloc_topology_destroy() or configured and loaded again.
- -
-
-
- - - - - - - -
-
-Functions
-
-
Finding Objects inside a CPU set
-
-
- - - - - - - - - - - - - - - - - - - - -

-Functions

static hwloc_obj_t hwloc_get_first_largest_obj_inside_cpuset (hwloc_topology_t topology, hwloc_const_cpuset_t set)
 
int hwloc_get_largest_objs_inside_cpuset (hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_t *restrict objs, int max)
 
static hwloc_obj_t hwloc_get_next_obj_inside_cpuset_by_depth (hwloc_topology_t topology, hwloc_const_cpuset_t set, int depth, hwloc_obj_t prev)
 
static hwloc_obj_t hwloc_get_next_obj_inside_cpuset_by_type (hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_type_t type, hwloc_obj_t prev)
 
static hwloc_obj_t hwloc_get_obj_inside_cpuset_by_depth (hwloc_topology_t topology, hwloc_const_cpuset_t set, int depth, unsigned idx)
 
static hwloc_obj_t hwloc_get_obj_inside_cpuset_by_type (hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_type_t type, unsigned idx)
 
static unsigned hwloc_get_nbobjs_inside_cpuset_by_depth (hwloc_topology_t topology, hwloc_const_cpuset_t set, int depth)
 
static int hwloc_get_nbobjs_inside_cpuset_by_type (hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_type_t type)
 
static int hwloc_get_obj_index_inside_cpuset (hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_t obj)
 
-

Detailed Description

-

Function Documentation

- -

◆ hwloc_get_first_largest_obj_inside_cpuset()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_get_first_largest_obj_inside_cpuset (hwloc_topology_t topology,
hwloc_const_cpuset_t set 
)
- 		-inlinestatic
-
- -

Get the first largest object included in the given cpuset set.

-
Returns
the first object that is included in set and whose parent is not.
-

This is convenient for iterating over all largest objects within a CPU set by doing a loop getting the first largest object and clearing its CPU set from the remaining CPU set.

- -
-
- -

◆ hwloc_get_largest_objs_inside_cpuset()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_get_largest_objs_inside_cpuset (hwloc_topology_t topology,
hwloc_const_cpuset_t set,
hwloc_obj_t *restrict objs,
int max 
)
-
- -

Get the set of largest objects covering exactly a given cpuset set.

-
Returns
the number of objects returned in objs.
- -
-
- -

◆ hwloc_get_nbobjs_inside_cpuset_by_depth()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - -
static unsigned hwloc_get_nbobjs_inside_cpuset_by_depth (hwloc_topology_t topology,
hwloc_const_cpuset_t set,
int depth 
)
- 		-inlinestatic
-
- -

Return the number of objects at depth depth included in CPU set set.

-
Note
Objects with empty CPU sets are ignored (otherwise they would be considered included in any given set).
-
-This function cannot work if objects at the given depth do not have CPU sets (I/O or Misc objects).
- -
-
- -

◆ hwloc_get_nbobjs_inside_cpuset_by_type()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - -
static int hwloc_get_nbobjs_inside_cpuset_by_type (hwloc_topology_t topology,
hwloc_const_cpuset_t set,
hwloc_obj_type_t type 
)
- 		-inlinestatic
-
- -

Return the number of objects of type type included in CPU set set.

-

If no object for that type exists inside CPU set set, 0 is returned. If there are several levels with objects of that type inside CPU set set, -1 is returned.

-
Note
Objects with empty CPU sets are ignored (otherwise they would be considered included in any given set).
-
-This function cannot work if objects of the given type do not have CPU sets (I/O objects).
- -
-
- -

◆ hwloc_get_next_obj_inside_cpuset_by_depth()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_get_next_obj_inside_cpuset_by_depth (hwloc_topology_t topology,
hwloc_const_cpuset_t set,
int depth,
hwloc_obj_t prev 
)
- 		-inlinestatic
-
- -

Return the next object at depth depth included in CPU set set.

-

If prev is NULL, return the first object at depth depth included in set. The next invokation should pass the previous return value in prev so as to obtain the next object in set.

-
Note
Objects with empty CPU sets are ignored (otherwise they would be considered included in any given set).
-
-This function cannot work if objects at the given depth do not have CPU sets (I/O or Misc objects).
- -
-
- -

◆ hwloc_get_next_obj_inside_cpuset_by_type()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_get_next_obj_inside_cpuset_by_type (hwloc_topology_t topology,
hwloc_const_cpuset_t set,
hwloc_obj_type_t type,
hwloc_obj_t prev 
)
- 		-inlinestatic
-
- -

Return the next object of type type included in CPU set set.

-

If there are multiple or no depth for given type, return NULL and let the caller fallback to hwloc_get_next_obj_inside_cpuset_by_depth().

-
Note
Objects with empty CPU sets are ignored (otherwise they would be considered included in any given set).
-
-This function cannot work if objects of the given type do not have CPU sets (I/O or Misc objects).
- -
-
- -

◆ hwloc_get_obj_index_inside_cpuset()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - -
static int hwloc_get_obj_index_inside_cpuset (hwloc_topology_t topology,
hwloc_const_cpuset_t set,
hwloc_obj_t obj 
)
- 		-inlinestatic
-
- -

Return the logical index among the objects included in CPU set set.

-

Consult all objects in the same level as obj and inside CPU set set in the logical order, and return the index of obj within them. If set covers the entire topology, this is the logical index of obj. Otherwise, this is similar to a logical index within the part of the topology defined by CPU set set.

-
Note
Objects with empty CPU sets are ignored (otherwise they would be considered included in any given set).
-
-This function cannot work if obj does not have CPU sets (I/O objects).
- -
-
- -

◆ hwloc_get_obj_inside_cpuset_by_depth()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_get_obj_inside_cpuset_by_depth (hwloc_topology_t topology,
hwloc_const_cpuset_t set,
int depth,
unsigned idx 
)
- 		-inlinestatic
-
- -

Return the (logically) idx -th object at depth depth included in CPU set set.

-
Note
Objects with empty CPU sets are ignored (otherwise they would be considered included in any given set).
-
-This function cannot work if objects at the given depth do not have CPU sets (I/O or Misc objects).
- -
-
- -

◆ hwloc_get_obj_inside_cpuset_by_type()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_get_obj_inside_cpuset_by_type (hwloc_topology_t topology,
hwloc_const_cpuset_t set,
hwloc_obj_type_t type,
unsigned idx 
)
- 		-inlinestatic
-
- -

Return the idx -th object of type type included in CPU set set.

-

If there are multiple or no depth for given type, return NULL and let the caller fallback to hwloc_get_obj_inside_cpuset_by_depth().

-
Note
Objects with empty CPU sets are ignored (otherwise they would be considered included in any given set).
-
-This function cannot work if objects of the given type do not have CPU sets (I/O or Misc objects).
- -
-
-
- - - - - - - -
-
-Functions
-
-
Finding Objects covering at least CPU set
-
-
- - - - - - - - - - -

-Functions

static hwloc_obj_t hwloc_get_child_covering_cpuset (hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_t parent)
 
static hwloc_obj_t hwloc_get_obj_covering_cpuset (hwloc_topology_t topology, hwloc_const_cpuset_t set)
 
static hwloc_obj_t hwloc_get_next_obj_covering_cpuset_by_depth (hwloc_topology_t topology, hwloc_const_cpuset_t set, int depth, hwloc_obj_t prev)
 
static hwloc_obj_t hwloc_get_next_obj_covering_cpuset_by_type (hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_type_t type, hwloc_obj_t prev)
 
-

Detailed Description

-

Function Documentation

- -

◆ hwloc_get_child_covering_cpuset()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_get_child_covering_cpuset (hwloc_topology_t topology,
hwloc_const_cpuset_t set,
hwloc_obj_t parent 
)
- 		-inlinestatic
-
- -

Get the child covering at least CPU set set.

-
Returns
NULL if no child matches or if set is empty.
-
Note
This function cannot work if parent does not have a CPU set (I/O or Misc objects).
- -
-
- -

◆ hwloc_get_next_obj_covering_cpuset_by_depth()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_get_next_obj_covering_cpuset_by_depth (hwloc_topology_t topology,
hwloc_const_cpuset_t set,
int depth,
hwloc_obj_t prev 
)
- 		-inlinestatic
-
- -

Iterate through same-depth objects covering at least CPU set set.

-

If object prev is NULL, return the first object at depth depth covering at least part of CPU set set. The next invokation should pass the previous return value in prev so as to obtain the next object covering at least another part of set.

-
Note
This function cannot work if objects at the given depth do not have CPU sets (I/O or Misc objects).
- -
-
- -

◆ hwloc_get_next_obj_covering_cpuset_by_type()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_get_next_obj_covering_cpuset_by_type (hwloc_topology_t topology,
hwloc_const_cpuset_t set,
hwloc_obj_type_t type,
hwloc_obj_t prev 
)
- 		-inlinestatic
-
- -

Iterate through same-type objects covering at least CPU set set.

-

If object prev is NULL, return the first object of type type covering at least part of CPU set set. The next invokation should pass the previous return value in prev so as to obtain the next object of type type covering at least another part of set.

-

If there are no or multiple depths for type type, NULL is returned. The caller may fallback to hwloc_get_next_obj_covering_cpuset_by_depth() for each depth.

-
Note
This function cannot work if objects of the given type do not have CPU sets (I/O or Misc objects).
- -
-
- -

◆ hwloc_get_obj_covering_cpuset()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_get_obj_covering_cpuset (hwloc_topology_t topology,
hwloc_const_cpuset_t set 
)
- 		-inlinestatic
-
- -

Get the lowest object covering at least CPU set set.

-
Returns
NULL if no object matches or if set is empty.
- -
-
-
- - - - - - - -
-
-Functions
-
-
Looking at Ancestor and Child Objects
-
-
- - - - - - - - - - - - -

-Functions

static hwloc_obj_t hwloc_get_ancestor_obj_by_depth (hwloc_topology_t topology, int depth, hwloc_obj_t obj)
 
static hwloc_obj_t hwloc_get_ancestor_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, hwloc_obj_t obj)
 
static hwloc_obj_t hwloc_get_common_ancestor_obj (hwloc_topology_t topology, hwloc_obj_t obj1, hwloc_obj_t obj2)
 
static int hwloc_obj_is_in_subtree (hwloc_topology_t topology, hwloc_obj_t obj, hwloc_obj_t subtree_root)
 
static hwloc_obj_t hwloc_get_next_child (hwloc_topology_t topology, hwloc_obj_t parent, hwloc_obj_t prev)
 
-

Detailed Description

-

Be sure to see the figure in Terms and Definitions that shows a complete topology tree, including depths, child/sibling/cousin relationships, and an example of an asymmetric topology where one package has fewer caches than its peers.

-

Function Documentation

- -

◆ hwloc_get_ancestor_obj_by_depth()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_get_ancestor_obj_by_depth (hwloc_topology_t topology,
int depth,
hwloc_obj_t obj 
)
- 		-inlinestatic
-
- -

Returns the ancestor object of obj at depth depth.

-
Note
depth should not be the depth of PU or NUMA objects since they are ancestors of no objects (except Misc or I/O). This function rather expects an intermediate level depth, such as the depth of Packages, Cores, or Caches.
- -
-
- -

◆ hwloc_get_ancestor_obj_by_type()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_get_ancestor_obj_by_type (hwloc_topology_t topology,
hwloc_obj_type_t type,
hwloc_obj_t obj 
)
- 		-inlinestatic
-
- -

Returns the ancestor object of obj with type type.

-
Note
type should not be HWLOC_OBJ_PU or HWLOC_OBJ_NUMANODE since these objects are ancestors of no objects (except Misc or I/O). This function rather expects an intermediate object type, such as HWLOC_OBJ_PACKAGE, HWLOC_OBJ_CORE, etc.
- -
-
- -

◆ hwloc_get_common_ancestor_obj()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_get_common_ancestor_obj (hwloc_topology_t topology,
hwloc_obj_t obj1,
hwloc_obj_t obj2 
)
- 		-inlinestatic
-
- -

Returns the common parent object to objects obj1 and obj2.

- -
-
- -

◆ hwloc_get_next_child()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_get_next_child (hwloc_topology_t topology,
hwloc_obj_t parent,
hwloc_obj_t prev 
)
- 		-inlinestatic
-
- -

Return the next child.

-

Return the next child among the normal children list, then among the memory children list, then among the I/O children list, then among the Misc children list.

-

If prev is NULL, return the first child.

-

Return NULL when there is no next child.

- -
-
- -

◆ hwloc_obj_is_in_subtree()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - -
static int hwloc_obj_is_in_subtree (hwloc_topology_t topology,
hwloc_obj_t obj,
hwloc_obj_t subtree_root 
)
- 		-inlinestatic
-
- -

Returns true if obj is inside the subtree beginning with ancestor object subtree_root.

-
Note
This function cannot work if obj and subtree_root objects do not have CPU sets (I/O or Misc objects).
- -
-
-
- - - - - - - -
-
-Functions
-
-
Kinds of object Type
-
-
- - - - - - - - - - - - - - -

-Functions

int hwloc_obj_type_is_normal (hwloc_obj_type_t type)
 
int hwloc_obj_type_is_io (hwloc_obj_type_t type)
 
int hwloc_obj_type_is_memory (hwloc_obj_type_t type)
 
int hwloc_obj_type_is_cache (hwloc_obj_type_t type)
 
int hwloc_obj_type_is_dcache (hwloc_obj_type_t type)
 
int hwloc_obj_type_is_icache (hwloc_obj_type_t type)
 
-

Detailed Description

-

Each object type is either Normal (i.e. hwloc_obj_type_is_normal() returns 1), or Memory (i.e. hwloc_obj_type_is_memory() returns 1) or I/O (i.e. hwloc_obj_type_is_io() returns 1) or Misc (i.e. equal to HWLOC_OBJ_MISC). It cannot be of more than one of these kinds.

-

Function Documentation

- -

◆ hwloc_obj_type_is_cache()

- -
-
- - - - - - - - -
int hwloc_obj_type_is_cache (hwloc_obj_type_t type)
-
- -

Check whether an object type is a CPU Cache (Data, Unified or Instruction).

-

Memory-side caches are not CPU caches.

-
Returns
1 if an object of type type is a Cache, 0 otherwise.
- -
-
- -

◆ hwloc_obj_type_is_dcache()

- -
-
- - - - - - - - -
int hwloc_obj_type_is_dcache (hwloc_obj_type_t type)
-
- -

Check whether an object type is a CPU Data or Unified Cache.

-

Memory-side caches are not CPU caches.

-
Returns
1 if an object of type type is a CPU Data or Unified Cache, 0 otherwise.
- -
-
- -

◆ hwloc_obj_type_is_icache()

- -
-
- - - - - - - - -
int hwloc_obj_type_is_icache (hwloc_obj_type_t type)
-
- -

Check whether an object type is a CPU Instruction Cache,.

-

Memory-side caches are not CPU caches.

-
Returns
1 if an object of type type is a CPU Instruction Cache, 0 otherwise.
- -
-
- -

◆ hwloc_obj_type_is_io()

- -
-
- - - - - - - - -
int hwloc_obj_type_is_io (hwloc_obj_type_t type)
-
- -

Check whether an object type is I/O.

-

I/O objects are objects attached to their parents in the I/O children list. This current includes Bridges, PCI and OS devices.

-
Returns
1 if an object of type type is a I/O object, 0 otherwise.
- -
-
- -

◆ hwloc_obj_type_is_memory()

- -
-
- - - - - - - - -
int hwloc_obj_type_is_memory (hwloc_obj_type_t type)
-
- -

Check whether an object type is Memory.

-

Memory objects are objects attached to their parents in the Memory children list. This current includes NUMA nodes and Memory-side caches.

-
Returns
1 if an object of type type is a Memory object, 0 otherwise.
- -
-
- -

◆ hwloc_obj_type_is_normal()

- -
-
- - - - - - - - -
int hwloc_obj_type_is_normal (hwloc_obj_type_t type)
-
- -

Check whether an object type is Normal.

-

Normal objects are objects of the main CPU hierarchy (Machine, Package, Core, PU, CPU caches, etc.), but they are not NUMA nodes, I/O devices or Misc objects.

-

They are attached to parent as Normal children, not as Memory, I/O or Misc children.

-
Returns
1 if an object of type type is a Normal object, 0 otherwise.
- -
-
-
- - - - - - - -
-
-Functions
-
-
Looking at Cache Objects
-
-
- - - - - - - - -

-Functions

static int hwloc_get_cache_type_depth (hwloc_topology_t topology, unsigned cachelevel, hwloc_obj_cache_type_t cachetype)
 
static hwloc_obj_t hwloc_get_cache_covering_cpuset (hwloc_topology_t topology, hwloc_const_cpuset_t set)
 
static hwloc_obj_t hwloc_get_shared_cache_covering_obj (hwloc_topology_t topology, hwloc_obj_t obj)
 
-

Detailed Description

-

Function Documentation

- -

◆ hwloc_get_cache_covering_cpuset()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_get_cache_covering_cpuset (hwloc_topology_t topology,
hwloc_const_cpuset_t set 
)
- 		-inlinestatic
-
- -

Get the first data (or unified) cache covering a cpuset set.

-
Returns
NULL if no cache matches.
- -
-
- -

◆ hwloc_get_cache_type_depth()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - -
static int hwloc_get_cache_type_depth (hwloc_topology_t topology,
unsigned cachelevel,
hwloc_obj_cache_type_t cachetype 
)
- 		-inlinestatic
-
- -

Find the depth of cache objects matching cache level and type.

-

Return the depth of the topology level that contains cache objects whose attributes match cachelevel and cachetype.

-

This function is identical to calling hwloc_get_type_depth() with the corresponding type such as HWLOC_OBJ_L1ICACHE, except that it may also return a Unified cache when looking for an instruction cache.

-

If no cache level matches, HWLOC_TYPE_DEPTH_UNKNOWN is returned.

-

If cachetype is HWLOC_OBJ_CACHE_UNIFIED, the depth of the unique matching unified cache level is returned.

-

If cachetype is HWLOC_OBJ_CACHE_DATA or HWLOC_OBJ_CACHE_INSTRUCTION, either a matching cache, or a unified cache is returned.

-

If cachetype is -1, it is ignored and multiple levels may match. The function returns either the depth of a uniquely matching level or HWLOC_TYPE_DEPTH_MULTIPLE.

- -
-
- -

◆ hwloc_get_shared_cache_covering_obj()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_get_shared_cache_covering_obj (hwloc_topology_t topology,
hwloc_obj_t obj 
)
- 		-inlinestatic
-
- -

Get the first data (or unified) cache shared between an object and somebody else.

-
Returns
NULL if no cache matches or if an invalid object is given.
- -
-
-
- - - - - - - -
-
-Functions
-
-
Finding objects, miscellaneous helpers
-
-
- - - - - - - - - - - - - - - - -

-Functions

int hwloc_bitmap_singlify_per_core (hwloc_topology_t topology, hwloc_bitmap_t cpuset, unsigned which)
 
static hwloc_obj_t hwloc_get_pu_obj_by_os_index (hwloc_topology_t topology, unsigned os_index)
 
static hwloc_obj_t hwloc_get_numanode_obj_by_os_index (hwloc_topology_t topology, unsigned os_index)
 
unsigned hwloc_get_closest_objs (hwloc_topology_t topology, hwloc_obj_t src, hwloc_obj_t *restrict objs, unsigned max)
 
static hwloc_obj_t hwloc_get_obj_below_by_type (hwloc_topology_t topology, hwloc_obj_type_t type1, unsigned idx1, hwloc_obj_type_t type2, unsigned idx2)
 
static hwloc_obj_t hwloc_get_obj_below_array_by_type (hwloc_topology_t topology, int nr, hwloc_obj_type_t *typev, unsigned *idxv)
 
hwloc_obj_t hwloc_get_obj_with_same_locality (hwloc_topology_t topology, hwloc_obj_t src, hwloc_obj_type_t type, const char *subtype, const char *nameprefix, unsigned long flags)
 
-

Detailed Description

-

Be sure to see the figure in Terms and Definitions that shows a complete topology tree, including depths, child/sibling/cousin relationships, and an example of an asymmetric topology where one package has fewer caches than its peers.

-

Function Documentation

- -

◆ hwloc_bitmap_singlify_per_core()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_bitmap_singlify_per_core (hwloc_topology_t topology,
hwloc_bitmap_t cpuset,
unsigned which 
)
-
- -

Remove simultaneous multithreading PUs from a CPU set.

-

For each core in topology, if cpuset contains some PUs of that core, modify cpuset to only keep a single PU for that core.

-

which specifies which PU will be kept. PU are considered in physical index order. If 0, for each core, the function keeps the first PU that was originally set in cpuset.

-

If which is larger than the number of PUs in a core there were originally set in cpuset, no PU is kept for that core.

-
Note
PUs that are not below a Core object are ignored (for instance if the topology does not contain any Core object). None of them is removed from cpuset.
- -
-
- -

◆ hwloc_get_closest_objs()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
unsigned hwloc_get_closest_objs (hwloc_topology_t topology,
hwloc_obj_t src,
hwloc_obj_t *restrict objs,
unsigned max 
)
-
- -

Do a depth-first traversal of the topology to find and sort.

-

all objects that are at the same depth than src. Report in objs up to max physically closest ones to src.

-
Returns
the number of objects returned in objs.
-
-0 if src is an I/O object.
-
Note
This function requires the src object to have a CPU set.
- -
-
- -

◆ hwloc_get_numanode_obj_by_os_index()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_get_numanode_obj_by_os_index (hwloc_topology_t topology,
unsigned os_index 
)
- 		-inlinestatic
-
- -

Returns the object of type HWLOC_OBJ_NUMANODE with os_index.

-

This function is useful for converting a nodeset into the NUMA node objects it contains. When retrieving the current binding (e.g. with hwloc_get_membind() with HWLOC_MEMBIND_BYNODESET), one may iterate over the bits of the resulting nodeset with hwloc_bitmap_foreach_begin(), and find the corresponding NUMA nodes with this function.

- -
-
- -

◆ hwloc_get_obj_below_array_by_type()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_get_obj_below_array_by_type (hwloc_topology_t topology,
int nr,
hwloc_obj_type_t * typev,
unsigned * idxv 
)
- 		-inlinestatic
-
- -

Find an object below a chain of objects specified by types and indexes.

-

This is a generalized version of hwloc_get_obj_below_by_type().

-

Arrays typev and idxv must contain nr types and indexes.

-

Start from the top system object and walk the arrays typev and idxv. For each type and logical index couple in the arrays, look under the previously found object to find the index-th object of the given type. Indexes are specified within the parent, not withing the entire system.

-

For instance, if nr is 3, typev contains NODE, PACKAGE and CORE, and idxv contains 0, 1 and 2, return the third core object below the second package below the first NUMA node.

-
Note
This function requires all these objects and the root object to have a CPU set.
- -
-
- -

◆ hwloc_get_obj_below_by_type()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_get_obj_below_by_type (hwloc_topology_t topology,
hwloc_obj_type_t type1,
unsigned idx1,
hwloc_obj_type_t type2,
unsigned idx2 
)
- 		-inlinestatic
-
- -

Find an object below another object, both specified by types and indexes.

-

Start from the top system object and find object of type type1 and logical index idx1. Then look below this object and find another object of type type2 and logical index idx2. Indexes are specified within the parent, not withing the entire system.

-

For instance, if type1 is PACKAGE, idx1 is 2, type2 is CORE and idx2 is 3, return the fourth core object below the third package.

-
Note
This function requires these objects to have a CPU set.
- -
-
- -

◆ hwloc_get_obj_with_same_locality()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
hwloc_obj_t hwloc_get_obj_with_same_locality (hwloc_topology_t topology,
hwloc_obj_t src,
hwloc_obj_type_t type,
const char * subtype,
const char * nameprefix,
unsigned long flags 
)
-
- -

Return an object of a different type with same locality.

-

If the source object src is a normal or memory type, this function returns an object of type type with same CPU and node sets, either below or above in the hierarchy.

-

If the source object src is a PCI or an OS device within a PCI device, the function may either return that PCI device, or another OS device in the same PCI parent. This may for instance be useful for converting between OS devices such as "nvml0" or "rsmi1" used in distance structures into the the PCI device, or the CUDA or OpenCL OS device that correspond to the same physical card.

-

If not NULL, parameter subtype only select objects whose subtype attribute exists and is subtype (case-insensitively), for instance "OpenCL" or "CUDA".

-

If not NULL, parameter nameprefix only selects objects whose name attribute exists and starts with nameprefix (case-insensitively), for instance "rsmi" for matching "rsmi0".

-

If multiple objects match, the first one is returned.

-

This function will not walk the hierarchy across bridges since the PCI locality may become different. This function cannot also convert between normal/memory objects and I/O or Misc objects.

-

flags must be 0 for now.

-
Returns
An object with identical locality, matching subtype and nameprefix if any.
-
-NULL if no matching object could be found, or if the source object and target type are incompatible, for instance if converting between CPU and I/O objects.
- -
-
- -

◆ hwloc_get_pu_obj_by_os_index()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_get_pu_obj_by_os_index (hwloc_topology_t topology,
unsigned os_index 
)
- 		-inlinestatic
-
- -

Returns the object of type HWLOC_OBJ_PU with os_index.

-

This function is useful for converting a CPU set into the PU objects it contains. When retrieving the current binding (e.g. with hwloc_get_cpubind()), one may iterate over the bits of the resulting CPU set with hwloc_bitmap_foreach_begin(), and find the corresponding PUs with this function.

- -
-
-
- - - - - - - -
-
-Enumerations | -Functions
-
-
Distributing items over a topology
-
-
- - - - -

-Enumerations

enum  hwloc_distrib_flags_e { HWLOC_DISTRIB_FLAG_REVERSE - }
 
- - - -

-Functions

static int hwloc_distrib (hwloc_topology_t topology, hwloc_obj_t *roots, unsigned n_roots, hwloc_cpuset_t *set, unsigned n, int until, unsigned long flags)
 
-

Detailed Description

-

Enumeration Type Documentation

- -

◆ hwloc_distrib_flags_e

- -
-
- - - - -
enum hwloc_distrib_flags_e
-
- -

Flags to be given to hwloc_distrib().

- - -
Enumerator
HWLOC_DISTRIB_FLAG_REVERSE 

Distrib in reverse order, starting from the last objects.

-
- -
-
-

Function Documentation

- -

◆ hwloc_distrib()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
static int hwloc_distrib (hwloc_topology_t topology,
hwloc_obj_t * roots,
unsigned n_roots,
hwloc_cpuset_t * set,
unsigned n,
int until,
unsigned long flags 
)
- 		-inlinestatic
-
- -

Distribute n items over the topology under roots.

-

Array set will be filled with n cpusets recursively distributed linearly over the topology under objects roots, down to depth until (which can be INT_MAX to distribute down to the finest level).

-

n_roots is usually 1 and roots only contains the topology root object so as to distribute over the entire topology.

-

This is typically useful when an application wants to distribute n threads over a machine, giving each of them as much private cache as possible and keeping them locally in number order.

-

The caller may typically want to also call hwloc_bitmap_singlify() before binding a thread so that it does not move at all.

-

flags should be 0 or a OR'ed set of hwloc_distrib_flags_e.

-
Note
This function requires the roots objects to have a CPU set.
- -
-
-
- - - - - - - -
-
-Functions
-
-
CPU and node sets of entire topologies
-
-
- - - - - - - - - - - - - - -

-Functions

hwloc_const_cpuset_t hwloc_topology_get_complete_cpuset (hwloc_topology_t topology)
 
hwloc_const_cpuset_t hwloc_topology_get_topology_cpuset (hwloc_topology_t topology)
 
hwloc_const_cpuset_t hwloc_topology_get_allowed_cpuset (hwloc_topology_t topology)
 
hwloc_const_nodeset_t hwloc_topology_get_complete_nodeset (hwloc_topology_t topology)
 
hwloc_const_nodeset_t hwloc_topology_get_topology_nodeset (hwloc_topology_t topology)
 
hwloc_const_nodeset_t hwloc_topology_get_allowed_nodeset (hwloc_topology_t topology)
 
-

Detailed Description

-

Function Documentation

- -

◆ hwloc_topology_get_allowed_cpuset()

- -
-
- - - - - - - - -
hwloc_const_cpuset_t hwloc_topology_get_allowed_cpuset (hwloc_topology_t topology)
-
- -

Get allowed CPU set.

-
Returns
the CPU set of allowed processors of the system.
-
Note
If the topology flag HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED was not set, this is identical to hwloc_topology_get_topology_cpuset(), which means all PUs are allowed.
-
-If HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED was set, applying hwloc_bitmap_intersects() on the result of this function and on an object cpuset checks whether there are allowed PUs inside that object. Applying hwloc_bitmap_and() returns the list of these allowed PUs.
-
-The returned cpuset is not newly allocated and should thus not be changed or freed, hwloc_bitmap_dup() must be used to obtain a local copy.
- -
-
- -

◆ hwloc_topology_get_allowed_nodeset()

- -
-
- - - - - - - - -
hwloc_const_nodeset_t hwloc_topology_get_allowed_nodeset (hwloc_topology_t topology)
-
- -

Get allowed node set.

-
Returns
the node set of allowed memory of the system.
-
Note
If the topology flag HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED was not set, this is identical to hwloc_topology_get_topology_nodeset(), which means all NUMA nodes are allowed.
-
-If HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED was set, applying hwloc_bitmap_intersects() on the result of this function and on an object nodeset checks whether there are allowed NUMA nodes inside that object. Applying hwloc_bitmap_and() returns the list of these allowed NUMA nodes.
-
-The returned nodeset is not newly allocated and should thus not be changed or freed, hwloc_bitmap_dup() must be used to obtain a local copy.
- -
-
- -

◆ hwloc_topology_get_complete_cpuset()

- -
-
- - - - - - - - -
hwloc_const_cpuset_t hwloc_topology_get_complete_cpuset (hwloc_topology_t topology)
-
- -

Get complete CPU set.

-
Returns
the complete CPU set of processors of the system.
-
Note
The returned cpuset is not newly allocated and should thus not be changed or freed; hwloc_bitmap_dup() must be used to obtain a local copy.
-
-This is equivalent to retrieving the root object complete CPU-set.
- -
-
- -

◆ hwloc_topology_get_complete_nodeset()

- -
-
- - - - - - - - -
hwloc_const_nodeset_t hwloc_topology_get_complete_nodeset (hwloc_topology_t topology)
-
- -

Get complete node set.

-
Returns
the complete node set of memory of the system.
-
Note
The returned nodeset is not newly allocated and should thus not be changed or freed; hwloc_bitmap_dup() must be used to obtain a local copy.
-
-This is equivalent to retrieving the root object complete nodeset.
- -
-
- -

◆ hwloc_topology_get_topology_cpuset()

- -
-
- - - - - - - - -
hwloc_const_cpuset_t hwloc_topology_get_topology_cpuset (hwloc_topology_t topology)
-
- -

Get topology CPU set.

-
Returns
the CPU set of processors of the system for which hwloc provides topology information. This is equivalent to the cpuset of the system object.
-
Note
The returned cpuset is not newly allocated and should thus not be changed or freed; hwloc_bitmap_dup() must be used to obtain a local copy.
-
-This is equivalent to retrieving the root object CPU-set.
- -
-
- -

◆ hwloc_topology_get_topology_nodeset()

- -
-
- - - - - - - - -
hwloc_const_nodeset_t hwloc_topology_get_topology_nodeset (hwloc_topology_t topology)
-
- -

Get topology node set.

-
Returns
the node set of memory of the system for which hwloc provides topology information. This is equivalent to the nodeset of the system object.
-
Note
The returned nodeset is not newly allocated and should thus not be changed or freed; hwloc_bitmap_dup() must be used to obtain a local copy.
-
-This is equivalent to retrieving the root object nodeset.
- -
-
-
- - - - - - - -
-
-Functions
-
-
Converting between CPU sets and node sets
-
-
- - - - - - -

-Functions

static int hwloc_cpuset_to_nodeset (hwloc_topology_t topology, hwloc_const_cpuset_t _cpuset, hwloc_nodeset_t nodeset)
 
static int hwloc_cpuset_from_nodeset (hwloc_topology_t topology, hwloc_cpuset_t _cpuset, hwloc_const_nodeset_t nodeset)
 
-

Detailed Description

-

Function Documentation

- -

◆ hwloc_cpuset_from_nodeset()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - -
static int hwloc_cpuset_from_nodeset (hwloc_topology_t topology,
hwloc_cpuset_t _cpuset,
hwloc_const_nodeset_t nodeset 
)
- 		-inlinestatic
-
- -

Convert a NUMA node set into a CPU set.

-

For each NUMA node included in the input nodeset, set the corresponding local PUs in the output _cpuset.

-

If some CPUs have no local NUMA nodes, this function never sets their indexes in the output CPU set, even if a full node set is given in input.

-

Hence the entire topology node set is converted into the set of all CPUs that have some local NUMA nodes.

- -
-
- -

◆ hwloc_cpuset_to_nodeset()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - -
static int hwloc_cpuset_to_nodeset (hwloc_topology_t topology,
hwloc_const_cpuset_t _cpuset,
hwloc_nodeset_t nodeset 
)
- 		-inlinestatic
-
- -

Convert a CPU set into a NUMA node set.

-

For each PU included in the input _cpuset, set the corresponding local NUMA node(s) in the output nodeset.

-

If some NUMA nodes have no CPUs at all, this function never sets their indexes in the output node set, even if a full CPU set is given in input.

-

Hence the entire topology CPU set is converted into the set of all nodes that have some local CPUs.

- -
-
-
- - - - - - - -
-
-Functions
-
-
Finding I/O objects
-
-
- - - - - - - - - - - - - - - - -

-Functions

static hwloc_obj_t hwloc_get_non_io_ancestor_obj (hwloc_topology_t topology, hwloc_obj_t ioobj)
 
static hwloc_obj_t hwloc_get_next_pcidev (hwloc_topology_t topology, hwloc_obj_t prev)
 
static hwloc_obj_t hwloc_get_pcidev_by_busid (hwloc_topology_t topology, unsigned domain, unsigned bus, unsigned dev, unsigned func)
 
static hwloc_obj_t hwloc_get_pcidev_by_busidstring (hwloc_topology_t topology, const char *busid)
 
static hwloc_obj_t hwloc_get_next_osdev (hwloc_topology_t topology, hwloc_obj_t prev)
 
static hwloc_obj_t hwloc_get_next_bridge (hwloc_topology_t topology, hwloc_obj_t prev)
 
static int hwloc_bridge_covers_pcibus (hwloc_obj_t bridge, unsigned domain, unsigned bus)
 
-

Detailed Description

-

Function Documentation

- -

◆ hwloc_bridge_covers_pcibus()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - -
static int hwloc_bridge_covers_pcibus (hwloc_obj_t bridge,
unsigned domain,
unsigned bus 
)
- 		-inlinestatic
-
- -
-
- -

◆ hwloc_get_next_bridge()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_get_next_bridge (hwloc_topology_t topology,
hwloc_obj_t prev 
)
- 		-inlinestatic
-
- -

Get the next bridge in the system.

-
Returns
the first bridge if prev is NULL.
- -
-
- -

◆ hwloc_get_next_osdev()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_get_next_osdev (hwloc_topology_t topology,
hwloc_obj_t prev 
)
- 		-inlinestatic
-
- -

Get the next OS device in the system.

-
Returns
the first OS device if prev is NULL.
- -
-
- -

◆ hwloc_get_next_pcidev()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_get_next_pcidev (hwloc_topology_t topology,
hwloc_obj_t prev 
)
- 		-inlinestatic
-
- -

Get the next PCI device in the system.

-
Returns
the first PCI device if prev is NULL.
- -
-
- -

◆ hwloc_get_non_io_ancestor_obj()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_get_non_io_ancestor_obj (hwloc_topology_t topology,
hwloc_obj_t ioobj 
)
- 		-inlinestatic
-
- -

Get the first non-I/O ancestor object.

-

Given the I/O object ioobj, find the smallest non-I/O ancestor object. This object (normal or memory) may then be used for binding because it has non-NULL CPU and node sets and because its locality is the same as ioobj.

-
Note
The resulting object is usually a normal object but it could also be a memory object (e.g. NUMA node) in future platforms if I/O objects ever get attached to memory instead of CPUs.
- -
-
- -

◆ hwloc_get_pcidev_by_busid()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_get_pcidev_by_busid (hwloc_topology_t topology,
unsigned domain,
unsigned bus,
unsigned dev,
unsigned func 
)
- 		-inlinestatic
-
- -

Find the PCI device object matching the PCI bus id given domain, bus device and function PCI bus id.

- -
-
- -

◆ hwloc_get_pcidev_by_busidstring()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_get_pcidev_by_busidstring (hwloc_topology_t topology,
const char * busid 
)
- 		-inlinestatic
-
- -

Find the PCI device object matching the PCI bus id given as a string xxxx:yy:zz.t or yy:zz.t.

- -
-
-
- - - - - - - -
-
-Macros | -Typedefs | -Functions
-
-
The bitmap API
-
-
- - - - - - -

-Macros

#define hwloc_bitmap_foreach_begin(id, bitmap)
 
#define hwloc_bitmap_foreach_end()
 
- - - - - -

-Typedefs

typedef struct hwloc_bitmap_s * hwloc_bitmap_t
 
typedef const struct hwloc_bitmap_s * hwloc_const_bitmap_t
 
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

-Functions

hwloc_bitmap_t hwloc_bitmap_alloc (void)
 
hwloc_bitmap_t hwloc_bitmap_alloc_full (void)
 
void hwloc_bitmap_free (hwloc_bitmap_t bitmap)
 
hwloc_bitmap_t hwloc_bitmap_dup (hwloc_const_bitmap_t bitmap)
 
int hwloc_bitmap_copy (hwloc_bitmap_t dst, hwloc_const_bitmap_t src)
 
int hwloc_bitmap_snprintf (char *restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap)
 
int hwloc_bitmap_asprintf (char **strp, hwloc_const_bitmap_t bitmap)
 
int hwloc_bitmap_sscanf (hwloc_bitmap_t bitmap, const char *restrict string)
 
int hwloc_bitmap_list_snprintf (char *restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap)
 
int hwloc_bitmap_list_asprintf (char **strp, hwloc_const_bitmap_t bitmap)
 
int hwloc_bitmap_list_sscanf (hwloc_bitmap_t bitmap, const char *restrict string)
 
int hwloc_bitmap_taskset_snprintf (char *restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap)
 
int hwloc_bitmap_taskset_asprintf (char **strp, hwloc_const_bitmap_t bitmap)
 
int hwloc_bitmap_taskset_sscanf (hwloc_bitmap_t bitmap, const char *restrict string)
 
void hwloc_bitmap_zero (hwloc_bitmap_t bitmap)
 
void hwloc_bitmap_fill (hwloc_bitmap_t bitmap)
 
int hwloc_bitmap_only (hwloc_bitmap_t bitmap, unsigned id)
 
int hwloc_bitmap_allbut (hwloc_bitmap_t bitmap, unsigned id)
 
int hwloc_bitmap_from_ulong (hwloc_bitmap_t bitmap, unsigned long mask)
 
int hwloc_bitmap_from_ith_ulong (hwloc_bitmap_t bitmap, unsigned i, unsigned long mask)
 
int hwloc_bitmap_from_ulongs (hwloc_bitmap_t bitmap, unsigned nr, const unsigned long *masks)
 
int hwloc_bitmap_set (hwloc_bitmap_t bitmap, unsigned id)
 
int hwloc_bitmap_set_range (hwloc_bitmap_t bitmap, unsigned begin, int end)
 
int hwloc_bitmap_set_ith_ulong (hwloc_bitmap_t bitmap, unsigned i, unsigned long mask)
 
int hwloc_bitmap_clr (hwloc_bitmap_t bitmap, unsigned id)
 
int hwloc_bitmap_clr_range (hwloc_bitmap_t bitmap, unsigned begin, int end)
 
int hwloc_bitmap_singlify (hwloc_bitmap_t bitmap)
 
unsigned long hwloc_bitmap_to_ulong (hwloc_const_bitmap_t bitmap)
 
unsigned long hwloc_bitmap_to_ith_ulong (hwloc_const_bitmap_t bitmap, unsigned i)
 
int hwloc_bitmap_to_ulongs (hwloc_const_bitmap_t bitmap, unsigned nr, unsigned long *masks)
 
int hwloc_bitmap_nr_ulongs (hwloc_const_bitmap_t bitmap)
 
int hwloc_bitmap_isset (hwloc_const_bitmap_t bitmap, unsigned id)
 
int hwloc_bitmap_iszero (hwloc_const_bitmap_t bitmap)
 
int hwloc_bitmap_isfull (hwloc_const_bitmap_t bitmap)
 
int hwloc_bitmap_first (hwloc_const_bitmap_t bitmap)
 
int hwloc_bitmap_next (hwloc_const_bitmap_t bitmap, int prev)
 
int hwloc_bitmap_last (hwloc_const_bitmap_t bitmap)
 
int hwloc_bitmap_weight (hwloc_const_bitmap_t bitmap)
 
int hwloc_bitmap_first_unset (hwloc_const_bitmap_t bitmap)
 
int hwloc_bitmap_next_unset (hwloc_const_bitmap_t bitmap, int prev)
 
int hwloc_bitmap_last_unset (hwloc_const_bitmap_t bitmap)
 
int hwloc_bitmap_or (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
 
int hwloc_bitmap_and (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
 
int hwloc_bitmap_andnot (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
 
int hwloc_bitmap_xor (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
 
int hwloc_bitmap_not (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap)
 
int hwloc_bitmap_intersects (hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
 
int hwloc_bitmap_isincluded (hwloc_const_bitmap_t sub_bitmap, hwloc_const_bitmap_t super_bitmap)
 
int hwloc_bitmap_isequal (hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
 
int hwloc_bitmap_compare_first (hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
 
int hwloc_bitmap_compare (hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
 
-

Detailed Description

-

The hwloc_bitmap_t type represents a set of integers (positive or null). A bitmap may be of infinite size (all bits are set after some point). A bitmap may even be full if all bits are set.

-

Bitmaps are used by hwloc for sets of OS processors (which may actually be hardware threads) as by hwloc_cpuset_t (a typedef for hwloc_bitmap_t), or sets of NUMA memory nodes as hwloc_nodeset_t (also a typedef for hwloc_bitmap_t). Those are used for cpuset and nodeset fields in the hwloc_obj structure, see Object Sets (hwloc_cpuset_t and hwloc_nodeset_t).

-

Both CPU and node sets are always indexed by OS physical number. However users should usually not build CPU and node sets manually (e.g. with hwloc_bitmap_set()). One should rather use existing object sets and combine them with hwloc_bitmap_or(), etc. For instance, binding the current thread on a pair of cores may be performed with:

hwloc_obj_t core1 = ... , core2 = ... ;
-
hwloc_bitmap_t set = hwloc_bitmap_alloc();
-
hwloc_bitmap_or(set, core1->cpuset, core2->cpuset);
-
hwloc_set_cpubind(topology, set, HWLOC_CPUBIND_THREAD);
-
hwloc_bitmap_free(set);
-
hwloc_set_cpubind
int hwloc_set_cpubind(hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags)
Bind current process or thread on CPUs given in physical bitmap set.
-
HWLOC_CPUBIND_THREAD
@ HWLOC_CPUBIND_THREAD
Bind current thread of current process.
Definition: hwloc.h:1162
-
hwloc_bitmap_or
int hwloc_bitmap_or(hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
Or bitmaps bitmap1 and bitmap2 and store the result in bitmap res.
-
hwloc_bitmap_free
void hwloc_bitmap_free(hwloc_bitmap_t bitmap)
Free bitmap bitmap.
-
hwloc_bitmap_t
struct hwloc_bitmap_s * hwloc_bitmap_t
Set of bits represented as an opaque pointer to an internal bitmap.
Definition: bitmap.h:68
-
hwloc_bitmap_alloc
hwloc_bitmap_t hwloc_bitmap_alloc(void)
Allocate a new empty bitmap.
-
hwloc_obj
Structure of a topology object.
Definition: hwloc.h:396
-
hwloc_obj::cpuset
hwloc_cpuset_t cpuset
CPUs covered by this object.
Definition: hwloc.h:512
-
Note
Most functions below return an int that may be negative in case of error. The usual error case would be an internal failure to realloc/extend the storage of the bitmap (errno would be set to ENOMEM).
-
-Several examples of using the bitmap API are available under the doc/examples/ directory in the source tree. Regression tests such as tests/hwloc/hwloc_bitmap*.c also make intensive use of this API.
-

Macro Definition Documentation

- -

◆ hwloc_bitmap_foreach_begin

- -
-
- - - - - - - - - - - - - - - - - - -
#define hwloc_bitmap_foreach_begin( id,
 bitmap 
)
-
- -

Loop macro iterating on bitmap bitmap.

-

The loop must start with hwloc_bitmap_foreach_begin() and end with hwloc_bitmap_foreach_end() followed by a terminating ';'.

-

id is the loop variable; it should be an unsigned int. The first iteration will set id to the lowest index in the bitmap. Successive iterations will iterate through, in order, all remaining indexes set in the bitmap. To be specific: each iteration will return a value for id such that hwloc_bitmap_isset(bitmap, id) is true.

-

The assert prevents the loop from being infinite if the bitmap is infinitely set.

- -
-
- -

◆ hwloc_bitmap_foreach_end

- -
-
- - - - - - - -
#define hwloc_bitmap_foreach_end()
-
- -

End of loop macro iterating on a bitmap.

-

Needs a terminating ';'.

-
See also
hwloc_bitmap_foreach_begin()
- -
-
-

Typedef Documentation

- -

◆ hwloc_bitmap_t

- -
-
- - - - -
typedef struct hwloc_bitmap_s* hwloc_bitmap_t
-
- -

Set of bits represented as an opaque pointer to an internal bitmap.

- -
-
- -

◆ hwloc_const_bitmap_t

- -
-
- - - - -
typedef const struct hwloc_bitmap_s* hwloc_const_bitmap_t
-
- -

a non-modifiable hwloc_bitmap_t

- -
-
-

Function Documentation

- -

◆ hwloc_bitmap_allbut()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_bitmap_allbut (hwloc_bitmap_t bitmap,
unsigned id 
)
-
- -

Fill the bitmap and clear the index id.

- -
-
- -

◆ hwloc_bitmap_alloc()

- -
-
- - - - - - - - -
hwloc_bitmap_t hwloc_bitmap_alloc (void )
-
- -

Allocate a new empty bitmap.

-
Returns
A valid bitmap or NULL.
-

The bitmap should be freed by a corresponding call to hwloc_bitmap_free().

- -
-
- -

◆ hwloc_bitmap_alloc_full()

- -
-
- - - - - - - - -
hwloc_bitmap_t hwloc_bitmap_alloc_full (void )
-
- -

Allocate a new full bitmap.

- -
-
- -

◆ hwloc_bitmap_and()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_bitmap_and (hwloc_bitmap_t res,
hwloc_const_bitmap_t bitmap1,
hwloc_const_bitmap_t bitmap2 
)
-
- -

And bitmaps bitmap1 and bitmap2 and store the result in bitmap res.

-

res can be the same as bitmap1 or bitmap2

- -
-
- -

◆ hwloc_bitmap_andnot()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_bitmap_andnot (hwloc_bitmap_t res,
hwloc_const_bitmap_t bitmap1,
hwloc_const_bitmap_t bitmap2 
)
-
- -

And bitmap bitmap1 and the negation of bitmap2 and store the result in bitmap res.

-

res can be the same as bitmap1 or bitmap2

- -
-
- -

◆ hwloc_bitmap_asprintf()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_bitmap_asprintf (char ** strp,
hwloc_const_bitmap_t bitmap 
)
-
- -

Stringify a bitmap into a newly allocated string.

-
Returns
-1 on error.
- -
-
- -

◆ hwloc_bitmap_clr()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_bitmap_clr (hwloc_bitmap_t bitmap,
unsigned id 
)
-
- -

Remove index id from bitmap bitmap.

- -
-
- -

◆ hwloc_bitmap_clr_range()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_bitmap_clr_range (hwloc_bitmap_t bitmap,
unsigned begin,
int end 
)
-
- -

Remove indexes from begin to end in bitmap bitmap.

-

If end is -1, the range is infinite.

- -
-
- -

◆ hwloc_bitmap_compare()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_bitmap_compare (hwloc_const_bitmap_t bitmap1,
hwloc_const_bitmap_t bitmap2 
)
-
- -

Compare bitmaps bitmap1 and bitmap2 in lexicographic order.

-

Lexicographic comparison of bitmaps, starting for their highest indexes. Compare last indexes first, then second, etc. The empty bitmap is considered lower than anything.

-
Returns
-1 if bitmap1 is considered smaller than bitmap2.
-
-1 if bitmap1 is considered larger than bitmap2.
-
-0 if bitmaps are equal (contrary to hwloc_bitmap_compare_first()).
-

For instance comparing binary bitmaps 0011 and 0110 returns -1 (hence 0011 is considered smaller than 0110). Comparing 00101 and 01010 returns -1 too.

-
Note
This is different from the non-existing hwloc_bitmap_compare_last() which would only compare the highest index of each bitmap.
- -
-
- -

◆ hwloc_bitmap_compare_first()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_bitmap_compare_first (hwloc_const_bitmap_t bitmap1,
hwloc_const_bitmap_t bitmap2 
)
-
- -

Compare bitmaps bitmap1 and bitmap2 using their lowest index.

-

A bitmap is considered smaller if its least significant bit is smaller. The empty bitmap is considered higher than anything (because its least significant bit does not exist).

-
Returns
-1 if bitmap1 is considered smaller than bitmap2.
-
-1 if bitmap1 is considered larger than bitmap2.
-

For instance comparing binary bitmaps 0011 and 0110 returns -1 (hence 0011 is considered smaller than 0110) because least significant bit of 0011 (0001) is smaller than least significant bit of 0110 (0010). Comparing 01001 and 00110 would also return -1 for the same reason.

-
Returns
0 if bitmaps are considered equal, even if they are not strictly equal. They just need to have the same least significant bit. For instance, comparing binary bitmaps 0010 and 0110 returns 0 because they have the same least significant bit.
- -
-
- -

◆ hwloc_bitmap_copy()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_bitmap_copy (hwloc_bitmap_t dst,
hwloc_const_bitmap_t src 
)
-
- -

Copy the contents of bitmap src into the already allocated bitmap dst.

- -
-
- -

◆ hwloc_bitmap_dup()

- -
-
- - - - - - - - -
hwloc_bitmap_t hwloc_bitmap_dup (hwloc_const_bitmap_t bitmap)
-
- -

Duplicate bitmap bitmap by allocating a new bitmap and copying bitmap contents.

-

If bitmap is NULL, NULL is returned.

- -
-
- -

◆ hwloc_bitmap_fill()

- -
-
- - - - - - - - -
void hwloc_bitmap_fill (hwloc_bitmap_t bitmap)
-
- -

Fill bitmap bitmap with all possible indexes (even if those objects don't exist or are otherwise unavailable)

- -
-
- -

◆ hwloc_bitmap_first()

- -
-
- - - - - - - - -
int hwloc_bitmap_first (hwloc_const_bitmap_t bitmap)
-
- -

Compute the first index (least significant bit) in bitmap bitmap.

-
Returns
-1 if no index is set in bitmap.
- -
-
- -

◆ hwloc_bitmap_first_unset()

- -
-
- - - - - - - - -
int hwloc_bitmap_first_unset (hwloc_const_bitmap_t bitmap)
-
- -

Compute the first unset index (least significant bit) in bitmap bitmap.

-
Returns
-1 if no index is unset in bitmap.
- -
-
- -

◆ hwloc_bitmap_free()

- -
-
- - - - - - - - -
void hwloc_bitmap_free (hwloc_bitmap_t bitmap)
-
- -

Free bitmap bitmap.

-

If bitmap is NULL, no operation is performed.

- -
-
- -

◆ hwloc_bitmap_from_ith_ulong()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_bitmap_from_ith_ulong (hwloc_bitmap_t bitmap,
unsigned i,
unsigned long mask 
)
-
- -

Setup bitmap bitmap from unsigned long mask used as i -th subset.

- -
-
- -

◆ hwloc_bitmap_from_ulong()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_bitmap_from_ulong (hwloc_bitmap_t bitmap,
unsigned long mask 
)
-
- -

Setup bitmap bitmap from unsigned long mask.

- -
-
- -

◆ hwloc_bitmap_from_ulongs()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_bitmap_from_ulongs (hwloc_bitmap_t bitmap,
unsigned nr,
const unsigned long * masks 
)
-
- -

Setup bitmap bitmap from unsigned longs masks used as first nr subsets.

- -
-
- -

◆ hwloc_bitmap_intersects()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_bitmap_intersects (hwloc_const_bitmap_t bitmap1,
hwloc_const_bitmap_t bitmap2 
)
-
- -

Test whether bitmaps bitmap1 and bitmap2 intersects.

-
Returns
1 if bitmaps intersect, 0 otherwise.
- -
-
- -

◆ hwloc_bitmap_isequal()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_bitmap_isequal (hwloc_const_bitmap_t bitmap1,
hwloc_const_bitmap_t bitmap2 
)
-
- -

Test whether bitmap bitmap1 is equal to bitmap bitmap2.

-
Returns
1 if bitmaps are equal, 0 otherwise.
- -
-
- -

◆ hwloc_bitmap_isfull()

- -
-
- - - - - - - - -
int hwloc_bitmap_isfull (hwloc_const_bitmap_t bitmap)
-
- -

Test whether bitmap bitmap is completely full.

-
Returns
1 if bitmap is full, 0 otherwise.
-
Note
A full bitmap is always infinitely set.
- -
-
- -

◆ hwloc_bitmap_isincluded()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_bitmap_isincluded (hwloc_const_bitmap_t sub_bitmap,
hwloc_const_bitmap_t super_bitmap 
)
-
- -

Test whether bitmap sub_bitmap is part of bitmap super_bitmap.

-
Returns
1 if sub_bitmap is included in super_bitmap, 0 otherwise.
-
Note
The empty bitmap is considered included in any other bitmap.
- -
-
- -

◆ hwloc_bitmap_isset()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_bitmap_isset (hwloc_const_bitmap_t bitmap,
unsigned id 
)
-
- -

Test whether index id is part of bitmap bitmap.

-
Returns
1 if the bit at index id is set in bitmap bitmap, 0 otherwise.
- -
-
- -

◆ hwloc_bitmap_iszero()

- -
-
- - - - - - - - -
int hwloc_bitmap_iszero (hwloc_const_bitmap_t bitmap)
-
- -

Test whether bitmap bitmap is empty.

-
Returns
1 if bitmap is empty, 0 otherwise.
- -
-
- -

◆ hwloc_bitmap_last()

- -
-
- - - - - - - - -
int hwloc_bitmap_last (hwloc_const_bitmap_t bitmap)
-
- -

Compute the last index (most significant bit) in bitmap bitmap.

-
Returns
-1 if no index is set in bitmap, or if bitmap is infinitely set.
- -
-
- -

◆ hwloc_bitmap_last_unset()

- -
-
- - - - - - - - -
int hwloc_bitmap_last_unset (hwloc_const_bitmap_t bitmap)
-
- -

Compute the last unset index (most significant bit) in bitmap bitmap.

-
Returns
-1 if no index is unset in bitmap, or if bitmap is infinitely set.
- -
-
- -

◆ hwloc_bitmap_list_asprintf()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_bitmap_list_asprintf (char ** strp,
hwloc_const_bitmap_t bitmap 
)
-
- -

Stringify a bitmap into a newly allocated list string.

-
Returns
-1 on error.
- -
-
- -

◆ hwloc_bitmap_list_snprintf()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_bitmap_list_snprintf (char *restrict buf,
size_t buflen,
hwloc_const_bitmap_t bitmap 
)
-
- -

Stringify a bitmap in the list format.

-

Lists are comma-separated indexes or ranges. Ranges are dash separated indexes. The last range may not have an ending indexes if the bitmap is infinitely set.

-

Up to buflen characters may be written in buffer buf.

-

If buflen is 0, buf may safely be NULL.

-
Returns
the number of characters that were actually written if not truncating, or that would have been written (not including the ending \0).
- -
-
- -

◆ hwloc_bitmap_list_sscanf()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_bitmap_list_sscanf (hwloc_bitmap_t bitmap,
const char *restrict string 
)
-
- -

Parse a list string and stores it in bitmap bitmap.

- -
-
- -

◆ hwloc_bitmap_next()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_bitmap_next (hwloc_const_bitmap_t bitmap,
int prev 
)
-
- -

Compute the next index in bitmap bitmap which is after index prev.

-

If prev is -1, the first index is returned.

-
Returns
-1 if no index with higher index is set in bitmap.
- -
-
- -

◆ hwloc_bitmap_next_unset()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_bitmap_next_unset (hwloc_const_bitmap_t bitmap,
int prev 
)
-
- -

Compute the next unset index in bitmap bitmap which is after index prev.

-

If prev is -1, the first unset index is returned.

-
Returns
-1 if no index with higher index is unset in bitmap.
- -
-
- -

◆ hwloc_bitmap_not()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_bitmap_not (hwloc_bitmap_t res,
hwloc_const_bitmap_t bitmap 
)
-
- -

Negate bitmap bitmap and store the result in bitmap res.

-

res can be the same as bitmap

- -
-
- -

◆ hwloc_bitmap_nr_ulongs()

- -
-
- - - - - - - - -
int hwloc_bitmap_nr_ulongs (hwloc_const_bitmap_t bitmap)
-
- -

Return the number of unsigned longs required for storing bitmap bitmap entirely.

-

This is the number of contiguous unsigned longs from the very first bit of the bitmap (even if unset) up to the last set bit. This is useful for knowing the nr parameter to pass to hwloc_bitmap_to_ulongs() (or which calls to hwloc_bitmap_to_ith_ulong() are needed) to entirely convert a bitmap into multiple unsigned longs.

-

When called on the output of hwloc_topology_get_topology_cpuset(), the returned number is large enough for all cpusets of the topology.

-
Returns
-1 if bitmap is infinite.
- -
-
- -

◆ hwloc_bitmap_only()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_bitmap_only (hwloc_bitmap_t bitmap,
unsigned id 
)
-
- -

Empty the bitmap bitmap and add bit id.

- -
-
- -

◆ hwloc_bitmap_or()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_bitmap_or (hwloc_bitmap_t res,
hwloc_const_bitmap_t bitmap1,
hwloc_const_bitmap_t bitmap2 
)
-
- -

Or bitmaps bitmap1 and bitmap2 and store the result in bitmap res.

-

res can be the same as bitmap1 or bitmap2

- -
-
- -

◆ hwloc_bitmap_set()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_bitmap_set (hwloc_bitmap_t bitmap,
unsigned id 
)
-
- -

Add index id in bitmap bitmap.

- -
-
- -

◆ hwloc_bitmap_set_ith_ulong()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_bitmap_set_ith_ulong (hwloc_bitmap_t bitmap,
unsigned i,
unsigned long mask 
)
-
- -

Replace i -th subset of bitmap bitmap with unsigned long mask.

- -
-
- -

◆ hwloc_bitmap_set_range()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_bitmap_set_range (hwloc_bitmap_t bitmap,
unsigned begin,
int end 
)
-
- -

Add indexes from begin to end in bitmap bitmap.

-

If end is -1, the range is infinite.

- -
-
- -

◆ hwloc_bitmap_singlify()

- -
-
- - - - - - - - -
int hwloc_bitmap_singlify (hwloc_bitmap_t bitmap)
-
- -

Keep a single index among those set in bitmap bitmap.

-

May be useful before binding so that the process does not have a chance of migrating between multiple processors in the original mask. Instead of running the task on any PU inside the given CPU set, the operating system scheduler will be forced to run it on a single of these PUs. It avoids a migration overhead and cache-line ping-pongs between PUs.

-
Note
This function is NOT meant to distribute multiple processes within a single CPU set. It always return the same single bit when called multiple times on the same input set. hwloc_distrib() may be used for generating CPU sets to distribute multiple tasks below a single multi-PU object.
-
-This function cannot be applied to an object set directly. It should be applied to a copy (which may be obtained with hwloc_bitmap_dup()).
- -
-
- -

◆ hwloc_bitmap_snprintf()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_bitmap_snprintf (char *restrict buf,
size_t buflen,
hwloc_const_bitmap_t bitmap 
)
-
- -

Stringify a bitmap.

-

Up to buflen characters may be written in buffer buf.

-

If buflen is 0, buf may safely be NULL.

-
Returns
the number of characters that were actually written if not truncating, or that would have been written (not including the ending \0).
- -
-
- -

◆ hwloc_bitmap_sscanf()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_bitmap_sscanf (hwloc_bitmap_t bitmap,
const char *restrict string 
)
-
- -

Parse a bitmap string and stores it in bitmap bitmap.

- -
-
- -

◆ hwloc_bitmap_taskset_asprintf()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_bitmap_taskset_asprintf (char ** strp,
hwloc_const_bitmap_t bitmap 
)
-
- -

Stringify a bitmap into a newly allocated taskset-specific string.

-
Returns
-1 on error.
- -
-
- -

◆ hwloc_bitmap_taskset_snprintf()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_bitmap_taskset_snprintf (char *restrict buf,
size_t buflen,
hwloc_const_bitmap_t bitmap 
)
-
- -

Stringify a bitmap in the taskset-specific format.

-

The taskset command manipulates bitmap strings that contain a single (possible very long) hexadecimal number starting with 0x.

-

Up to buflen characters may be written in buffer buf.

-

If buflen is 0, buf may safely be NULL.

-
Returns
the number of characters that were actually written if not truncating, or that would have been written (not including the ending \0).
- -
-
- -

◆ hwloc_bitmap_taskset_sscanf()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_bitmap_taskset_sscanf (hwloc_bitmap_t bitmap,
const char *restrict string 
)
-
- -

Parse a taskset-specific bitmap string and stores it in bitmap bitmap.

- -
-
- -

◆ hwloc_bitmap_to_ith_ulong()

- -
-
- - - - - - - - - - - - - - - - - - -
unsigned long hwloc_bitmap_to_ith_ulong (hwloc_const_bitmap_t bitmap,
unsigned i 
)
-
- -

Convert the i -th subset of bitmap bitmap into unsigned long mask.

- -
-
- -

◆ hwloc_bitmap_to_ulong()

- -
-
- - - - - - - - -
unsigned long hwloc_bitmap_to_ulong (hwloc_const_bitmap_t bitmap)
-
- -

Convert the beginning part of bitmap bitmap into unsigned long mask.

- -
-
- -

◆ hwloc_bitmap_to_ulongs()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_bitmap_to_ulongs (hwloc_const_bitmap_t bitmap,
unsigned nr,
unsigned long * masks 
)
-
- -

Convert the first nr subsets of bitmap bitmap into the array of nr unsigned long masks.

-

nr may be determined earlier with hwloc_bitmap_nr_ulongs().

-
Returns
0
- -
-
- -

◆ hwloc_bitmap_weight()

- -
-
- - - - - - - - -
int hwloc_bitmap_weight (hwloc_const_bitmap_t bitmap)
-
- -

Compute the "weight" of bitmap bitmap (i.e., number of indexes that are in the bitmap).

-
Returns
the number of indexes that are in the bitmap.
-
--1 if bitmap is infinitely set.
- -
-
- -

◆ hwloc_bitmap_xor()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_bitmap_xor (hwloc_bitmap_t res,
hwloc_const_bitmap_t bitmap1,
hwloc_const_bitmap_t bitmap2 
)
-
- -

Xor bitmaps bitmap1 and bitmap2 and store the result in bitmap res.

-

res can be the same as bitmap1 or bitmap2

- -
-
- -

◆ hwloc_bitmap_zero()

- -
-
- - - - - - - - -
void hwloc_bitmap_zero (hwloc_bitmap_t bitmap)
-
- -

Empty the bitmap bitmap.

- -
-
-
- - - - - - - -
-
-Enumerations | -Functions
-
-
Exporting Topologies to XML
-
-
- - - - -

-Enumerations

enum  hwloc_topology_export_xml_flags_e { HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1 - }
 
- - - - - - - - - - - - - - - -

-Functions

int hwloc_topology_export_xml (hwloc_topology_t topology, const char *xmlpath, unsigned long flags)
 
int hwloc_topology_export_xmlbuffer (hwloc_topology_t topology, char **xmlbuffer, int *buflen, unsigned long flags)
 
void hwloc_free_xmlbuffer (hwloc_topology_t topology, char *xmlbuffer)
 
void hwloc_topology_set_userdata_export_callback (hwloc_topology_t topology, void(*export_cb)(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj))
 
int hwloc_export_obj_userdata (void *reserved, hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length)
 
int hwloc_export_obj_userdata_base64 (void *reserved, hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length)
 
void hwloc_topology_set_userdata_import_callback (hwloc_topology_t topology, void(*import_cb)(hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length))
 
-

Detailed Description

-

Enumeration Type Documentation

- -

◆ hwloc_topology_export_xml_flags_e

- -
-
- - - - -
enum hwloc_topology_export_xml_flags_e
-
- -

Flags for exporting XML topologies.

-

Flags to be given as a OR'ed set to hwloc_topology_export_xml().

- - -
Enumerator
HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1 

Export XML that is loadable by hwloc v1.x. However, the export may miss some details about the topology.

-
- -
-
-

Function Documentation

- -

◆ hwloc_export_obj_userdata()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_export_obj_userdata (void * reserved,
hwloc_topology_t topology,
hwloc_obj_t obj,
const char * name,
const void * buffer,
size_t length 
)
-
- -

Export some object userdata to XML.

-

This function may only be called from within the export() callback passed to hwloc_topology_set_userdata_export_callback(). It may be invoked one of multiple times to export some userdata to XML. The buffer content of length length is stored with optional name name.

-

When importing this XML file, the import() callback (if set) will be called exactly as many times as hwloc_export_obj_userdata() was called during export(). It will receive the corresponding name, buffer and length arguments.

-

reserved, topology and obj must be the first three parameters that were given to the export callback.

-

Only printable characters may be exported to XML string attributes. If a non-printable character is passed in name or buffer, the function returns -1 with errno set to EINVAL.

-

If exporting binary data, the application should first encode into printable characters only (or use hwloc_export_obj_userdata_base64()). It should also take care of portability issues if the export may be reimported on a different architecture.

- -
-
- -

◆ hwloc_export_obj_userdata_base64()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_export_obj_userdata_base64 (void * reserved,
hwloc_topology_t topology,
hwloc_obj_t obj,
const char * name,
const void * buffer,
size_t length 
)
-
- -

Encode and export some object userdata to XML.

-

This function is similar to hwloc_export_obj_userdata() but it encodes the input buffer into printable characters before exporting. On import, decoding is automatically performed before the data is given to the import() callback if any.

-

This function may only be called from within the export() callback passed to hwloc_topology_set_userdata_export_callback().

-

The function does not take care of portability issues if the export may be reimported on a different architecture.

- -
-
- -

◆ hwloc_free_xmlbuffer()

- -
-
- - - - - - - - - - - - - - - - - - -
void hwloc_free_xmlbuffer (hwloc_topology_t topology,
char * xmlbuffer 
)
-
- -

Free a buffer allocated by hwloc_topology_export_xmlbuffer()

- -
-
- -

◆ hwloc_topology_export_xml()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_topology_export_xml (hwloc_topology_t topology,
const char * xmlpath,
unsigned long flags 
)
-
- -

Export the topology into an XML file.

-

This file may be loaded later through hwloc_topology_set_xml().

-

By default, the latest export format is used, which means older hwloc releases (e.g. v1.x) will not be able to import it. Exporting to v1.x specific XML format is possible using flag HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1 but it may miss some details about the topology. If there is any chance that the exported file may ever be imported back by a process using hwloc 1.x, one should consider detecting it at runtime and using the corresponding export format.

-

flags is a OR'ed set of hwloc_topology_export_xml_flags_e.

-
Returns
-1 if a failure occured.
-
Note
See also hwloc_topology_set_userdata_export_callback() for exporting application-specific object userdata.
-
-The topology-specific userdata pointer is ignored when exporting to XML.
-
-Only printable characters may be exported to XML string attributes. Any other character, especially any non-ASCII character, will be silently dropped.
-
-If name is "-", the XML output is sent to the standard output.
- -
-
- -

◆ hwloc_topology_export_xmlbuffer()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_topology_export_xmlbuffer (hwloc_topology_t topology,
char ** xmlbuffer,
int * buflen,
unsigned long flags 
)
-
- -

Export the topology into a newly-allocated XML memory buffer.

-

xmlbuffer is allocated by the callee and should be freed with hwloc_free_xmlbuffer() later in the caller.

-

This memory buffer may be loaded later through hwloc_topology_set_xmlbuffer().

-

By default, the latest export format is used, which means older hwloc releases (e.g. v1.x) will not be able to import it. Exporting to v1.x specific XML format is possible using flag HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1 but it may miss some details about the topology. If there is any chance that the exported buffer may ever be imported back by a process using hwloc 1.x, one should consider detecting it at runtime and using the corresponding export format.

-

The returned buffer ends with a \0 that is included in the returned length.

-

flags is a OR'ed set of hwloc_topology_export_xml_flags_e.

-
Returns
-1 if a failure occured.
-
Note
See also hwloc_topology_set_userdata_export_callback() for exporting application-specific object userdata.
-
-The topology-specific userdata pointer is ignored when exporting to XML.
-
-Only printable characters may be exported to XML string attributes. Any other character, especially any non-ASCII character, will be silently dropped.
- -
-
- -

◆ hwloc_topology_set_userdata_export_callback()

- -
-
- - - - - - - - - - - - - - - - - - -
void hwloc_topology_set_userdata_export_callback (hwloc_topology_t topology,
void(*)(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj) export_cb 
)
-
- -

Set the application-specific callback for exporting object userdata.

-

The object userdata pointer is not exported to XML by default because hwloc does not know what it contains.

-

This function lets applications set export_cb to a callback function that converts this opaque userdata into an exportable string.

-

export_cb is invoked during XML export for each object whose userdata pointer is not NULL. The callback should use hwloc_export_obj_userdata() or hwloc_export_obj_userdata_base64() to actually export something to XML (possibly multiple times per object).

-

export_cb may be set to NULL if userdata should not be exported to XML.

-
Note
The topology-specific userdata pointer is ignored when exporting to XML.
- -
-
- -

◆ hwloc_topology_set_userdata_import_callback()

- -
-
- - - - - - - - - - - - - - - - - - -
void hwloc_topology_set_userdata_import_callback (hwloc_topology_t topology,
void(*)(hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length) import_cb 
)
-
- -

Set the application-specific callback for importing userdata.

-

On XML import, userdata is ignored by default because hwloc does not know how to store it in memory.

-

This function lets applications set import_cb to a callback function that will get the XML-stored userdata and store it in the object as expected by the application.

-

import_cb is called during hwloc_topology_load() as many times as hwloc_export_obj_userdata() was called during export. The topology is not entirely setup yet. Object attributes are ready to consult, but links between objects are not.

-

import_cb may be NULL if userdata should be ignored during import.

-
Note
buffer contains length characters followed by a null byte ('\0').
-
-This function should be called before hwloc_topology_load().
-
-The topology-specific userdata pointer is ignored when importing from XML.
- -
-
-
- - - - - - - -
-
-Enumerations | -Functions
-
-
Exporting Topologies to Synthetic
-
-
- - - - -

-Enumerations

enum  hwloc_topology_export_synthetic_flags_e { HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_EXTENDED_TYPES -, HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_ATTRS -, HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_V1 -, HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_IGNORE_MEMORY - }
 
- - - -

-Functions

int hwloc_topology_export_synthetic (hwloc_topology_t topology, char *buffer, size_t buflen, unsigned long flags)
 
-

Detailed Description

-

Enumeration Type Documentation

- -

◆ hwloc_topology_export_synthetic_flags_e

- -
-
- - - - -
enum hwloc_topology_export_synthetic_flags_e
-
- -

Flags for exporting synthetic topologies.

-

Flags to be given as a OR'ed set to hwloc_topology_export_synthetic().

- - - - - -
Enumerator
HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_EXTENDED_TYPES 

Export extended types such as L2dcache as basic types such as Cache.

-

This is required if loading the synthetic description with hwloc < 1.9.

-
HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_ATTRS 

Do not export level attributes.

-

Ignore level attributes such as memory/cache sizes or PU indexes. This is required if loading the synthetic description with hwloc < 1.10.

-
HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_V1 

Export the memory hierarchy as expected in hwloc 1.x.

-

Instead of attaching memory children to levels, export single NUMA node child as normal intermediate levels, when possible. This is required if loading the synthetic description with hwloc 1.x. However this may fail if some objects have multiple local NUMA nodes.

-
HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_IGNORE_MEMORY 

Do not export memory information.

-

Only export the actual hierarchy of normal CPU-side objects and ignore where memory is attached. This is useful for when the hierarchy of CPUs is what really matters, but it behaves as if there was a single machine-wide NUMA node.

-
- -
-
-

Function Documentation

- -

◆ hwloc_topology_export_synthetic()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_topology_export_synthetic (hwloc_topology_t topology,
char * buffer,
size_t buflen,
unsigned long flags 
)
-
- -

Export the topology as a synthetic string.

-

At most buflen characters will be written in buffer, including the terminating \0.

-

This exported string may be given back to hwloc_topology_set_synthetic().

-

flags is a OR'ed set of hwloc_topology_export_synthetic_flags_e.

-
Returns
The number of characters that were written, not including the terminating \0.
-
--1 if the topology could not be exported, for instance if it is not symmetric.
-
Note
I/O and Misc children are ignored, the synthetic string only describes normal children.
-
-A 1024-byte buffer should be large enough for exporting topologies in the vast majority of cases.
- -
-
-
- - - - - - - -
-
-Data Structures | -Enumerations | -Functions
-
-
Retrieve distances between objects
-
-
- - - - -

-Data Structures

struct  hwloc_distances_s
 
- - - - - -

-Enumerations

enum  hwloc_distances_kind_e {
-  HWLOC_DISTANCES_KIND_FROM_OS -, HWLOC_DISTANCES_KIND_FROM_USER -, HWLOC_DISTANCES_KIND_MEANS_LATENCY -, HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH -,
-  HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES -
- }
 
enum  hwloc_distances_transform_e { HWLOC_DISTANCES_TRANSFORM_REMOVE_NULL -, HWLOC_DISTANCES_TRANSFORM_LINKS -, HWLOC_DISTANCES_TRANSFORM_MERGE_SWITCH_PORTS -, HWLOC_DISTANCES_TRANSFORM_TRANSITIVE_CLOSURE - }
 
- - - - - - - - - - - - - - - -

-Functions

int hwloc_distances_get (hwloc_topology_t topology, unsigned *nr, struct hwloc_distances_s **distances, unsigned long kind, unsigned long flags)
 
int hwloc_distances_get_by_depth (hwloc_topology_t topology, int depth, unsigned *nr, struct hwloc_distances_s **distances, unsigned long kind, unsigned long flags)
 
int hwloc_distances_get_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned *nr, struct hwloc_distances_s **distances, unsigned long kind, unsigned long flags)
 
int hwloc_distances_get_by_name (hwloc_topology_t topology, const char *name, unsigned *nr, struct hwloc_distances_s **distances, unsigned long flags)
 
const char * hwloc_distances_get_name (hwloc_topology_t topology, struct hwloc_distances_s *distances)
 
void hwloc_distances_release (hwloc_topology_t topology, struct hwloc_distances_s *distances)
 
int hwloc_distances_transform (hwloc_topology_t topology, struct hwloc_distances_s *distances, enum hwloc_distances_transform_e transform, void *transform_attr, unsigned long flags)
 
-

Detailed Description

-

Enumeration Type Documentation

- -

◆ hwloc_distances_kind_e

- -
-
- - - - -
enum hwloc_distances_kind_e
-
- -

Kinds of distance matrices.

-

The kind attribute of struct hwloc_distances_s is a OR'ed set of kinds.

-

A kind of format HWLOC_DISTANCES_KIND_FROM_* specifies where the distance information comes from, if known.

-

A kind of format HWLOC_DISTANCES_KIND_MEANS_* specifies whether values are latencies or bandwidths, if applicable.

- - - - - - -
Enumerator
HWLOC_DISTANCES_KIND_FROM_OS 

These distances were obtained from the operating system or hardware.

-
HWLOC_DISTANCES_KIND_FROM_USER 

These distances were provided by the user.

-
HWLOC_DISTANCES_KIND_MEANS_LATENCY 

Distance values are similar to latencies between objects. Values are smaller for closer objects, hence minimal on the diagonal of the matrix (distance between an object and itself). It could also be the number of network hops between objects, etc.

-
HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH 

Distance values are similar to bandwidths between objects. Values are higher for closer objects, hence maximal on the diagonal of the matrix (distance between an object and itself). Such values are currently ignored for distance-based grouping.

-
HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES 

This distances structure covers objects of different types. This may apply to the "NVLinkBandwidth" structure in presence of a NVSwitch or POWER processor NVLink port.

-
- -
-
- -

◆ hwloc_distances_transform_e

- -
-
- - - - -
enum hwloc_distances_transform_e
-
- -

Transformations of distances structures.

- - - - - -
Enumerator
HWLOC_DISTANCES_TRANSFORM_REMOVE_NULL 

Remove NULL objects from the distances structure.

-

Every object that was replaced with NULL in the objs array is removed and the values array is updated accordingly.

-

At least 2 objects must remain, otherwise hwloc_distances_transform() will return -1 with errno set to EINVAL.

-

kind will be updated with or without HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES according to the remaining objects.

-
HWLOC_DISTANCES_TRANSFORM_LINKS 

Replace bandwidth values with a number of links.

-

Usually all values will be either 0 (no link) or 1 (one link). However some matrices could get larger values if some pairs of peers are connected by different numbers of links.

-

Values on the diagonal are set to 0.

-

This transformation only applies to bandwidth matrices.

-
HWLOC_DISTANCES_TRANSFORM_MERGE_SWITCH_PORTS 

Merge switches with multiple ports into a single object. This currently only applies to NVSwitches where GPUs seem connected to different separate switch ports in the NVLinkBandwidth matrix. This transformation will replace all of them with the same port connected to all GPUs. Other ports are removed by applying HWLOC_DISTANCES_TRANSFORM_REMOVE_NULL internally.

-
HWLOC_DISTANCES_TRANSFORM_TRANSITIVE_CLOSURE 

Apply a transitive closure to the matrix to connect objects across switches. This currently only applies to GPUs and NVSwitches in the NVLinkBandwidth matrix. All pairs of GPUs will be reported as directly connected.

-
- -
-
-

Function Documentation

- -

◆ hwloc_distances_get()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_distances_get (hwloc_topology_t topology,
unsigned * nr,
struct hwloc_distances_s ** distances,
unsigned long kind,
unsigned long flags 
)
-
- -

Retrieve distance matrices.

-

Retrieve distance matrices from the topology into the distances array.

-

flags is currently unused, should be 0.

-

kind serves as a filter. If 0, all distance matrices are returned. If it contains some HWLOC_DISTANCES_KIND_FROM_*, only distance matrices whose kind matches one of these are returned. If it contains some HWLOC_DISTANCES_KIND_MEANS_*, only distance matrices whose kind matches one of these are returned.

-

On input, nr points to the number of distance matrices that may be stored in distances. On output, nr points to the number of distance matrices that were actually found, even if some of them couldn't be stored in distances. Distance matrices that couldn't be stored are ignored, but the function still returns success (0). The caller may find out by comparing the value pointed by nr before and after the function call.

-

Each distance matrix returned in the distances array should be released by the caller using hwloc_distances_release().

- -
-
- -

◆ hwloc_distances_get_by_depth()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_distances_get_by_depth (hwloc_topology_t topology,
int depth,
unsigned * nr,
struct hwloc_distances_s ** distances,
unsigned long kind,
unsigned long flags 
)
-
- -

Retrieve distance matrices for object at a specific depth in the topology.

-

Identical to hwloc_distances_get() with the additional depth filter.

- -
-
- -

◆ hwloc_distances_get_by_name()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_distances_get_by_name (hwloc_topology_t topology,
const char * name,
unsigned * nr,
struct hwloc_distances_s ** distances,
unsigned long flags 
)
-
- -

Retrieve a distance matrix with the given name.

-

Usually only one distances structure may match a given name.

-

The name of the most common structure is "NUMALatency". Others include "XGMIBandwidth", "XGMIHops", "XeLinkBandwidth", and "NVLinkBandwidth".

- -
-
- -

◆ hwloc_distances_get_by_type()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_distances_get_by_type (hwloc_topology_t topology,
hwloc_obj_type_t type,
unsigned * nr,
struct hwloc_distances_s ** distances,
unsigned long kind,
unsigned long flags 
)
-
- -

Retrieve distance matrices for object of a specific type.

-

Identical to hwloc_distances_get() with the additional type filter.

- -
-
- -

◆ hwloc_distances_get_name()

- -
-
- - - - - - - - - - - - - - - - - - -
const char* hwloc_distances_get_name (hwloc_topology_t topology,
struct hwloc_distances_s * distances 
)
-
- -

Get a description of what a distances structure contains.

-

For instance "NUMALatency" for hardware-provided NUMA distances (ACPI SLIT), or NULL if unknown.

- -
-
- -

◆ hwloc_distances_release()

- -
-
- - - - - - - - - - - - - - - - - - -
void hwloc_distances_release (hwloc_topology_t topology,
struct hwloc_distances_s * distances 
)
-
- -

Release a distance matrix structure previously returned by hwloc_distances_get().

-
Note
This function is not required if the structure is removed with hwloc_distances_release_remove().
- -
-
- -

◆ hwloc_distances_transform()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_distances_transform (hwloc_topology_t topology,
struct hwloc_distances_s * distances,
enum hwloc_distances_transform_e transform,
void * transform_attr,
unsigned long flags 
)
-
- -

Apply a transformation to a distances structure.

-

Modify a distances structure that was previously obtained with hwloc_distances_get() or one of its variants.

-

This modifies the local copy of the distances structures but does not modify the distances information stored inside the topology (retrieved by another call to hwloc_distances_get() or exported to XML). To do so, one should add a new distances structure with same name, kind, objects and values (see Add distances between objects) and then remove this old one with hwloc_distances_release_remove().

-

transform must be one of the transformations listed in hwloc_distances_transform_e.

-

These transformations may modify the contents of the objs or values arrays.

-

transform_attr must be NULL for now.

-

flags must be 0 for now.

-
Note
Objects in distances array objs may be directly modified in place without using hwloc_distances_transform(). One may use hwloc_get_obj_with_same_locality() to easily convert between similar objects of different types.
- -
-
-
- - - - - - - -
-
-Functions
-
-
Helpers for consulting distance matrices
-
-
- - - - - - -

-Functions

static int hwloc_distances_obj_index (struct hwloc_distances_s *distances, hwloc_obj_t obj)
 
static int hwloc_distances_obj_pair_values (struct hwloc_distances_s *distances, hwloc_obj_t obj1, hwloc_obj_t obj2, hwloc_uint64_t *value1to2, hwloc_uint64_t *value2to1)
 
-

Detailed Description

-

Function Documentation

- -

◆ hwloc_distances_obj_index()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static int hwloc_distances_obj_index (struct hwloc_distances_s * distances,
hwloc_obj_t obj 
)
- 		-inlinestatic
-
- -

Find the index of an object in a distances structure.

-
Returns
-1 if object obj is not involved in structure distances.
- -
-
- -

◆ hwloc_distances_obj_pair_values()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
static int hwloc_distances_obj_pair_values (struct hwloc_distances_s * distances,
hwloc_obj_t obj1,
hwloc_obj_t obj2,
hwloc_uint64_t * value1to2,
hwloc_uint64_t * value2to1 
)
- 		-inlinestatic
-
- -

Find the values between two objects in a distance matrices.

-

The distance from obj1 to obj2 is stored in the value pointed by value1to2 and reciprocally.

-
Returns
-1 if object obj1 or obj2 is not involved in structure distances.
- -
-
-
- - - - - - - -
-
-Typedefs | -Enumerations | -Functions
-
-
Add distances between objects
-
-
- - - - -

-Typedefs

typedef void * hwloc_distances_add_handle_t
 
- - - -

-Enumerations

enum  hwloc_distances_add_flag_e { HWLOC_DISTANCES_ADD_FLAG_GROUP -, HWLOC_DISTANCES_ADD_FLAG_GROUP_INACCURATE - }
 
- - - - - - - -

-Functions

hwloc_distances_add_handle_t hwloc_distances_add_create (hwloc_topology_t topology, const char *name, unsigned long kind, unsigned long flags)
 
int hwloc_distances_add_values (hwloc_topology_t topology, hwloc_distances_add_handle_t handle, unsigned nbobjs, hwloc_obj_t *objs, hwloc_uint64_t *values, unsigned long flags)
 
int hwloc_distances_add_commit (hwloc_topology_t topology, hwloc_distances_add_handle_t handle, unsigned long flags)
 
-

Detailed Description

-

The usual way to add distances is:

hwloc_distances_add_handle_t handle;
-
int err = -1;
-
handle = hwloc_distances_add_create(topology, "name", kind, 0);
-
if (handle) {
-
err = hwloc_distances_add_values(topology, handle, nbobjs, objs, values, 0);
-
if (!err)
-
err = hwloc_distances_add_commit(topology, handle, flags);
-
}
-
hwloc_distances_add_commit
int hwloc_distances_add_commit(hwloc_topology_t topology, hwloc_distances_add_handle_t handle, unsigned long flags)
Commit a new distances structure.
-
hwloc_distances_add_handle_t
void * hwloc_distances_add_handle_t
Handle to a new distances structure during its addition to the topology.
Definition: distances.h:331
-
hwloc_distances_add_create
hwloc_distances_add_handle_t hwloc_distances_add_create(hwloc_topology_t topology, const char *name, unsigned long kind, unsigned long flags)
Create a new empty distances structure.
-
hwloc_distances_add_values
int hwloc_distances_add_values(hwloc_topology_t topology, hwloc_distances_add_handle_t handle, unsigned nbobjs, hwloc_obj_t *objs, hwloc_uint64_t *values, unsigned long flags)
Specify the objects and values in a new empty distances structure.
-

If err is 0 at the end, then addition was successful.

-

Typedef Documentation

- -

◆ hwloc_distances_add_handle_t

- -
-
- - - - -
typedef void* hwloc_distances_add_handle_t
-
- -

Handle to a new distances structure during its addition to the topology.

- -
-
-

Enumeration Type Documentation

- -

◆ hwloc_distances_add_flag_e

- -
-
- - - - -
enum hwloc_distances_add_flag_e
-
- -

Flags for adding a new distances to a topology.

- - - -
Enumerator
HWLOC_DISTANCES_ADD_FLAG_GROUP 

Try to group objects based on the newly provided distance information. This is ignored for distances between objects of different types.

-
HWLOC_DISTANCES_ADD_FLAG_GROUP_INACCURATE 

If grouping, consider the distance values as inaccurate and relax the comparisons during the grouping algorithms. The actual accuracy may be modified through the HWLOC_GROUPING_ACCURACY environment variable (see Environment Variables).

-
- -
-
-

Function Documentation

- -

◆ hwloc_distances_add_commit()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_distances_add_commit (hwloc_topology_t topology,
hwloc_distances_add_handle_t handle,
unsigned long flags 
)
-
- -

Commit a new distances structure.

-

This function finalizes the distances structure and inserts in it the topology.

-

Parameter handle was previously returned by hwloc_distances_add_create(). Then objects and values were specified with hwloc_distances_add_values().

-

flags configures the behavior of the function using an optional OR'ed set of hwloc_distances_add_flag_e. It may be used to request the grouping of existing objects based on distances.

-

On error, the temporary distances structure and its content are destroyed.

-
Returns
0 on success.
-
--1 on error.
- -
-
- -

◆ hwloc_distances_add_create()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
hwloc_distances_add_handle_t hwloc_distances_add_create (hwloc_topology_t topology,
const char * name,
unsigned long kind,
unsigned long flags 
)
-
- -

Create a new empty distances structure.

-

Create an empty distances structure to be filled with hwloc_distances_add_values() and then committed with hwloc_distances_add_commit().

-

Parameter name is optional, it may be NULL. Otherwise, it will be copied internally and may later be freed by the caller.

-

kind specifies the kind of distance as a OR'ed set of hwloc_distances_kind_e. Kind HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES will be automatically set according to objects having different types in hwloc_distances_add_values().

-

flags must be 0 for now.

-
Returns
A hwloc_distances_add_handle_t that should then be passed to hwloc_distances_add_values() and hwloc_distances_add_commit().
-
-NULL on error.
- -
-
- -

◆ hwloc_distances_add_values()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_distances_add_values (hwloc_topology_t topology,
hwloc_distances_add_handle_t handle,
unsigned nbobjs,
hwloc_obj_t * objs,
hwloc_uint64_t * values,
unsigned long flags 
)
-
- -

Specify the objects and values in a new empty distances structure.

-

Specify the objects and values for a new distances structure that was returned as a handle by hwloc_distances_add_create(). The structure must then be committed with hwloc_distances_add_commit().

-

The number of objects is nbobjs and the array of objects is objs. Distance values are stored as a one-dimension array in values. The distance from object i to object j is in slot i*nbobjs+j.

-

nbobjs must be at least 2.

-

Arrays objs and values will be copied internally, they may later be freed by the caller.

-

On error, the temporary distances structure and its content are destroyed.

-

flags must be 0 for now.

-
Returns
0 on success.
-
--1 on error.
- -
-
-
- - - - - - - -
-
-Functions
-
-
Remove distances between objects
-
-
- - - - - - - - - - -

-Functions

int hwloc_distances_remove (hwloc_topology_t topology)
 
int hwloc_distances_remove_by_depth (hwloc_topology_t topology, int depth)
 
static int hwloc_distances_remove_by_type (hwloc_topology_t topology, hwloc_obj_type_t type)
 
int hwloc_distances_release_remove (hwloc_topology_t topology, struct hwloc_distances_s *distances)
 
-

Detailed Description

-

Function Documentation

- -

◆ hwloc_distances_release_remove()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_distances_release_remove (hwloc_topology_t topology,
struct hwloc_distances_s * distances 
)
-
- -

Release and remove the given distance matrice from the topology.

-

This function includes a call to hwloc_distances_release().

- -
-
- -

◆ hwloc_distances_remove()

- -
-
- - - - - - - - -
int hwloc_distances_remove (hwloc_topology_t topology)
-
- -

Remove all distance matrices from a topology.

-

Remove all distance matrices, either provided by the user or gathered through the OS.

-

If these distances were used to group objects, these additional Group objects are not removed from the topology.

- -
-
- -

◆ hwloc_distances_remove_by_depth()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_distances_remove_by_depth (hwloc_topology_t topology,
int depth 
)
-
- -

Remove distance matrices for objects at a specific depth in the topology.

-

Identical to hwloc_distances_remove() but only applies to one level of the topology.

- -
-
- -

◆ hwloc_distances_remove_by_type()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static int hwloc_distances_remove_by_type (hwloc_topology_t topology,
hwloc_obj_type_t type 
)
- 		-inlinestatic
-
- -

Remove distance matrices for objects of a specific type in the topology.

-

Identical to hwloc_distances_remove() but only applies to one level of the topology.

- -
-
-
- - - - - - - -
-
-Data Structures | -Typedefs | -Enumerations | -Functions
-
-
Comparing memory node attributes for finding where to allocate on
-
-
- - - - -

-Data Structures

struct  hwloc_location
 
- - - -

-Typedefs

typedef unsigned hwloc_memattr_id_t
 
- - - - - - - -

-Enumerations

enum  hwloc_memattr_id_e {
-  HWLOC_MEMATTR_ID_CAPACITY -, HWLOC_MEMATTR_ID_LOCALITY -, HWLOC_MEMATTR_ID_BANDWIDTH -, HWLOC_MEMATTR_ID_READ_BANDWIDTH -,
-  HWLOC_MEMATTR_ID_WRITE_BANDWIDTH -, HWLOC_MEMATTR_ID_LATENCY -, HWLOC_MEMATTR_ID_READ_LATENCY -, HWLOC_MEMATTR_ID_WRITE_LATENCY -,
-  HWLOC_MEMATTR_ID_MAX -
- }
 
enum  hwloc_location_type_e { HWLOC_LOCATION_TYPE_CPUSET -, HWLOC_LOCATION_TYPE_OBJECT - }
 
enum  hwloc_local_numanode_flag_e { HWLOC_LOCAL_NUMANODE_FLAG_LARGER_LOCALITY -, HWLOC_LOCAL_NUMANODE_FLAG_SMALLER_LOCALITY -, HWLOC_LOCAL_NUMANODE_FLAG_ALL - }
 
- - - - - - - - - - - -

-Functions

int hwloc_memattr_get_by_name (hwloc_topology_t topology, const char *name, hwloc_memattr_id_t *id)
 
int hwloc_get_local_numanode_objs (hwloc_topology_t topology, struct hwloc_location *location, unsigned *nr, hwloc_obj_t *nodes, unsigned long flags)
 
int hwloc_memattr_get_value (hwloc_topology_t topology, hwloc_memattr_id_t attribute, hwloc_obj_t target_node, struct hwloc_location *initiator, unsigned long flags, hwloc_uint64_t *value)
 
int hwloc_memattr_get_best_target (hwloc_topology_t topology, hwloc_memattr_id_t attribute, struct hwloc_location *initiator, unsigned long flags, hwloc_obj_t *best_target, hwloc_uint64_t *value)
 
int hwloc_memattr_get_best_initiator (hwloc_topology_t topology, hwloc_memattr_id_t attribute, hwloc_obj_t target, unsigned long flags, struct hwloc_location *best_initiator, hwloc_uint64_t *value)
 
-

Detailed Description

-

Platforms with heterogeneous memory require ways to decide whether a buffer should be allocated on "fast" memory (such as HBM), "normal" memory (DDR) or even "slow" but large-capacity memory (non-volatile memory). These memory nodes are called "Targets" while the CPU accessing them is called the "Initiator". Access performance depends on their locality (NUMA platforms) as well as the intrinsic performance of the targets (heterogeneous platforms).

-

The following attributes describe the performance of memory accesses from an Initiator to a memory Target, for instance their latency or bandwidth. Initiators performing these memory accesses are usually some PUs or Cores (described as a CPU set). Hence a Core may choose where to allocate a memory buffer by comparing the attributes of different target memory nodes nearby.

-

There are also some attributes that are system-wide. Their value does not depend on a specific initiator performing an access. The memory node Capacity is an example of such attribute without initiator.

-

One way to use this API is to start with a cpuset describing the Cores where a program is bound. The best target NUMA node for allocating memory in this program on these Cores may be obtained by passing this cpuset as an initiator to hwloc_memattr_get_best_target() with the relevant memory attribute. For instance, if the code is latency limited, use the Latency attribute.

-

A more flexible approach consists in getting the list of local NUMA nodes by passing this cpuset to hwloc_get_local_numanode_objs(). Attribute values for these nodes, if any, may then be obtained with hwloc_memattr_get_value() and manually compared with the desired criteria.

-
See also
An example is available in doc/examples/memory-attributes.c in the source tree.
-
Note
The API also supports specific objects as initiator, but it is currently not used internally by hwloc. Users may for instance use it to provide custom performance values for host memory accesses performed by GPUs.
-
-The interface actually also accepts targets that are not NUMA nodes.
-

Typedef Documentation

- -

◆ hwloc_memattr_id_t

- -
-
- - - - -
typedef unsigned hwloc_memattr_id_t
-
- -

A memory attribute identifier. May be either one of hwloc_memattr_id_e or a new id returned by hwloc_memattr_register().

- -
-
-

Enumeration Type Documentation

- -

◆ hwloc_local_numanode_flag_e

- -
-
- - - - -
enum hwloc_local_numanode_flag_e
-
- -

Flags for selecting target NUMA nodes.

- - - - -
Enumerator
HWLOC_LOCAL_NUMANODE_FLAG_LARGER_LOCALITY 

Select NUMA nodes whose locality is larger than the given cpuset. For instance, if a single PU (or its cpuset) is given in initiator, select all nodes close to the package that contains this PU.

-
HWLOC_LOCAL_NUMANODE_FLAG_SMALLER_LOCALITY 

Select NUMA nodes whose locality is smaller than the given cpuset. For instance, if a package (or its cpuset) is given in initiator, also select nodes that are attached to only a half of that package.

-
HWLOC_LOCAL_NUMANODE_FLAG_ALL 

Select all NUMA nodes in the topology. The initiator initiator is ignored.

-
- -
-
- -

◆ hwloc_location_type_e

- -
-
- - - - -
enum hwloc_location_type_e
-
- -

Type of location.

- - - -
Enumerator
HWLOC_LOCATION_TYPE_CPUSET 

Location is given as a cpuset, in the location cpuset union field.

-
HWLOC_LOCATION_TYPE_OBJECT 

Location is given as an object, in the location object union field.

-
- -
-
- -

◆ hwloc_memattr_id_e

- -
-
- - - - -
enum hwloc_memattr_id_e
-
- -

Memory node attributes.

- - - - - - - - - -
Enumerator
HWLOC_MEMATTR_ID_CAPACITY 

The "Capacity" is returned in bytes (local_memory attribute in objects).

-

Best capacity nodes are nodes with higher capacity.

-

No initiator is involved when looking at this attribute. The corresponding attribute flags are HWLOC_MEMATTR_FLAG_HIGHER_FIRST.

-
HWLOC_MEMATTR_ID_LOCALITY 

The "Locality" is returned as the number of PUs in that locality (e.g. the weight of its cpuset).

-

Best locality nodes are nodes with smaller locality (nodes that are local to very few PUs). Poor locality nodes are nodes with larger locality (nodes that are local to the entire machine).

-

No initiator is involved when looking at this attribute. The corresponding attribute flags are HWLOC_MEMATTR_FLAG_HIGHER_FIRST.

-
HWLOC_MEMATTR_ID_BANDWIDTH 

The "Bandwidth" is returned in MiB/s, as seen from the given initiator location.

-

Best bandwidth nodes are nodes with higher bandwidth.

-

The corresponding attribute flags are HWLOC_MEMATTR_FLAG_HIGHER_FIRST and HWLOC_MEMATTR_FLAG_NEED_INITIATOR.

-

This is the average bandwidth for read and write accesses. If the platform provides individual read and write bandwidths but no explicit average value, hwloc computes and returns the average.

-
HWLOC_MEMATTR_ID_READ_BANDWIDTH 

The "ReadBandwidth" is returned in MiB/s, as seen from the given initiator location.

-

Best bandwidth nodes are nodes with higher bandwidth.

-

The corresponding attribute flags are HWLOC_MEMATTR_FLAG_HIGHER_FIRST and HWLOC_MEMATTR_FLAG_NEED_INITIATOR.

-
HWLOC_MEMATTR_ID_WRITE_BANDWIDTH 

The "WriteBandwidth" is returned in MiB/s, as seen from the given initiator location.

-

Best bandwidth nodes are nodes with higher bandwidth.

-

The corresponding attribute flags are HWLOC_MEMATTR_FLAG_HIGHER_FIRST and HWLOC_MEMATTR_FLAG_NEED_INITIATOR.

-
HWLOC_MEMATTR_ID_LATENCY 

The "Latency" is returned as nanoseconds, as seen from the given initiator location.

-

Best latency nodes are nodes with smaller latency.

-

The corresponding attribute flags are HWLOC_MEMATTR_FLAG_LOWER_FIRST and HWLOC_MEMATTR_FLAG_NEED_INITIATOR.

-

This is the average latency for read and write accesses. If the platform provides individual read and write latencies but no explicit average value, hwloc computes and returns the average.

-
HWLOC_MEMATTR_ID_READ_LATENCY 

The "ReadLatency" is returned as nanoseconds, as seen from the given initiator location.

-

Best latency nodes are nodes with smaller latency.

-

The corresponding attribute flags are HWLOC_MEMATTR_FLAG_LOWER_FIRST and HWLOC_MEMATTR_FLAG_NEED_INITIATOR.

-
HWLOC_MEMATTR_ID_WRITE_LATENCY 

The "WriteLatency" is returned as nanoseconds, as seen from the given initiator location.

-

Best latency nodes are nodes with smaller latency.

-

The corresponding attribute flags are HWLOC_MEMATTR_FLAG_LOWER_FIRST and HWLOC_MEMATTR_FLAG_NEED_INITIATOR.

-
- -
-
-

Function Documentation

- -

◆ hwloc_get_local_numanode_objs()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_get_local_numanode_objs (hwloc_topology_t topology,
struct hwloc_location * location,
unsigned * nr,
hwloc_obj_t * nodes,
unsigned long flags 
)
-
- -

Return an array of local NUMA nodes.

-

By default only select the NUMA nodes whose locality is exactly the given location. More nodes may be selected if additional flags are given as a OR'ed set of hwloc_local_numanode_flag_e.

-

If location is given as an explicit object, its CPU set is used to find NUMA nodes with the corresponding locality. If the object does not have a CPU set (e.g. I/O object), the CPU parent (where the I/O object is attached) is used.

-

On input, nr points to the number of nodes that may be stored in the nodes array. On output, nr will be changed to the number of stored nodes, or the number of nodes that would have been stored if there were enough room.

-
Note
Some of these NUMA nodes may not have any memory attribute values and hence not be reported as actual targets in other functions.
-
-The number of NUMA nodes in the topology (obtained by hwloc_bitmap_weight() on the root object nodeset) may be used to allocate the nodes array.
-
-When an object CPU set is given as locality, for instance a Package, and when flags contain both HWLOC_LOCAL_NUMANODE_FLAG_LARGER_LOCALITY and HWLOC_LOCAL_NUMANODE_FLAG_SMALLER_LOCALITY, the returned array corresponds to the nodeset of that object.
- -
-
- -

◆ hwloc_memattr_get_best_initiator()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_memattr_get_best_initiator (hwloc_topology_t topology,
hwloc_memattr_id_t attribute,
hwloc_obj_t target,
unsigned long flags,
struct hwloc_location * best_initiator,
hwloc_uint64_t * value 
)
-
- -

Return the best initiator for the given attribute and target NUMA node.

-

If the attribute does not relate to a specific initiator (it does not have the flag HWLOC_MEMATTR_FLAG_NEED_INITIATOR), -1 is returned and errno is set to EINVAL.

-

If value is non NULL, the corresponding value is returned there.

-

If multiple initiators have the same attribute values, only one is returned (and there is no way to clarify how that one is chosen). Applications that want to detect initiators with identical/similar values, or that want to look at values for multiple attributes, should rather get all values using hwloc_memattr_get_value() and manually select the initiator they consider the best.

-

The returned initiator should not be modified or freed, it belongs to the topology.

-

flags must be 0 for now.

-

If there are no matching initiators, -1 is returned with errno set to ENOENT;

- -
-
- -

◆ hwloc_memattr_get_best_target()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_memattr_get_best_target (hwloc_topology_t topology,
hwloc_memattr_id_t attribute,
struct hwloc_location * initiator,
unsigned long flags,
hwloc_obj_t * best_target,
hwloc_uint64_t * value 
)
-
- -

Return the best target NUMA node for the given attribute and initiator.

-

If the attribute does not relate to a specific initiator (it does not have the flag HWLOC_MEMATTR_FLAG_NEED_INITIATOR), location initiator is ignored and may be NULL.

-

If value is non NULL, the corresponding value is returned there.

-

If multiple targets have the same attribute values, only one is returned (and there is no way to clarify how that one is chosen). Applications that want to detect targets with identical/similar values, or that want to look at values for multiple attributes, should rather get all values using hwloc_memattr_get_value() and manually select the target they consider the best.

-

flags must be 0 for now.

-

If there are no matching targets, -1 is returned with errno set to ENOENT;

-
Note
The initiator initiator should be of type HWLOC_LOCATION_TYPE_CPUSET when refering to accesses performed by CPU cores. HWLOC_LOCATION_TYPE_OBJECT is currently unused internally by hwloc, but users may for instance use it to provide custom information about host memory accesses performed by GPUs.
- -
-
- -

◆ hwloc_memattr_get_by_name()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_memattr_get_by_name (hwloc_topology_t topology,
const char * name,
hwloc_memattr_id_t * id 
)
-
- -

Return the identifier of the memory attribute with the given name.

- -
-
- -

◆ hwloc_memattr_get_value()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_memattr_get_value (hwloc_topology_t topology,
hwloc_memattr_id_t attribute,
hwloc_obj_t target_node,
struct hwloc_location * initiator,
unsigned long flags,
hwloc_uint64_t * value 
)
-
- -

Return an attribute value for a specific target NUMA node.

-

If the attribute does not relate to a specific initiator (it does not have the flag HWLOC_MEMATTR_FLAG_NEED_INITIATOR), location initiator is ignored and may be NULL.

-

flags must be 0 for now.

-
Note
The initiator initiator should be of type HWLOC_LOCATION_TYPE_CPUSET when refering to accesses performed by CPU cores. HWLOC_LOCATION_TYPE_OBJECT is currently unused internally by hwloc, but users may for instance use it to provide custom information about host memory accesses performed by GPUs.
- -
-
-
- - - - - - - -
-
-Enumerations | -Functions
-
-
Managing memory attributes
-
-
- - - - -

-Enumerations

enum  hwloc_memattr_flag_e { HWLOC_MEMATTR_FLAG_HIGHER_FIRST = (1UL<<0) -, HWLOC_MEMATTR_FLAG_LOWER_FIRST = (1UL<<1) -, HWLOC_MEMATTR_FLAG_NEED_INITIATOR = (1UL<<2) - }
 
- - - - - - - - - - - - - -

-Functions

int hwloc_memattr_get_name (hwloc_topology_t topology, hwloc_memattr_id_t attribute, const char **name)
 
int hwloc_memattr_get_flags (hwloc_topology_t topology, hwloc_memattr_id_t attribute, unsigned long *flags)
 
int hwloc_memattr_register (hwloc_topology_t topology, const char *name, unsigned long flags, hwloc_memattr_id_t *id)
 
int hwloc_memattr_set_value (hwloc_topology_t topology, hwloc_memattr_id_t attribute, hwloc_obj_t target_node, struct hwloc_location *initiator, unsigned long flags, hwloc_uint64_t value)
 
int hwloc_memattr_get_targets (hwloc_topology_t topology, hwloc_memattr_id_t attribute, struct hwloc_location *initiator, unsigned long flags, unsigned *nr, hwloc_obj_t *targets, hwloc_uint64_t *values)
 
int hwloc_memattr_get_initiators (hwloc_topology_t topology, hwloc_memattr_id_t attribute, hwloc_obj_t target_node, unsigned long flags, unsigned *nr, struct hwloc_location *initiators, hwloc_uint64_t *values)
 
-

Detailed Description

-

Enumeration Type Documentation

- -

◆ hwloc_memattr_flag_e

- -
-
- - - - -
enum hwloc_memattr_flag_e
-
- -

Memory attribute flags. Given to hwloc_memattr_register() and returned by hwloc_memattr_get_flags().

- - - - -
Enumerator
HWLOC_MEMATTR_FLAG_HIGHER_FIRST 

The best nodes for this memory attribute are those with the higher values. For instance Bandwidth.

-
HWLOC_MEMATTR_FLAG_LOWER_FIRST 

The best nodes for this memory attribute are those with the lower values. For instance Latency.

-
HWLOC_MEMATTR_FLAG_NEED_INITIATOR 

The value returned for this memory attribute depends on the given initiator. For instance Bandwidth and Latency, but not Capacity.

-
- -
-
-

Function Documentation

- -

◆ hwloc_memattr_get_flags()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_memattr_get_flags (hwloc_topology_t topology,
hwloc_memattr_id_t attribute,
unsigned long * flags 
)
-
- -

Return the flags of the given attribute.

-

Flags are a OR'ed set of hwloc_memattr_flag_e.

- -
-
- -

◆ hwloc_memattr_get_initiators()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_memattr_get_initiators (hwloc_topology_t topology,
hwloc_memattr_id_t attribute,
hwloc_obj_t target_node,
unsigned long flags,
unsigned * nr,
struct hwloc_location * initiators,
hwloc_uint64_t * values 
)
-
- -

Return the initiators that have values for a given attribute for a specific target NUMA node.

-

Return initiators for the given attribute and target node in the initiators array. If values is not NULL, the corresponding attribute values are stored in the array it points to.

-

On input, nr points to the number of initiators that may be stored in the array initiators (and values). On output, nr points to the number of initiators (and values) that were actually found, even if some of them couldn't be stored in the array. Initiators that couldn't be stored are ignored, but the function still returns success (0). The caller may find out by comparing the value pointed by nr before and after the function call.

-

The returned initiators should not be modified or freed, they belong to the topology.

-

flags must be 0 for now.

-

If the attribute does not relate to a specific initiator (it does not have the flag HWLOC_MEMATTR_FLAG_NEED_INITIATOR), no initiator is returned.

-
Note
This function is meant for tools and debugging (listing internal information) rather than for application queries. Applications should rather select useful NUMA nodes with hwloc_get_local_numanode_objs() and then look at their attribute values for some relevant initiators.
- -
-
- -

◆ hwloc_memattr_get_name()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_memattr_get_name (hwloc_topology_t topology,
hwloc_memattr_id_t attribute,
const char ** name 
)
-
- -

Return the name of a memory attribute.

- -
-
- -

◆ hwloc_memattr_get_targets()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_memattr_get_targets (hwloc_topology_t topology,
hwloc_memattr_id_t attribute,
struct hwloc_location * initiator,
unsigned long flags,
unsigned * nr,
hwloc_obj_t * targets,
hwloc_uint64_t * values 
)
-
- -

Return the target NUMA nodes that have some values for a given attribute.

-

Return targets for the given attribute in the targets array (for the given initiator if any). If values is not NULL, the corresponding attribute values are stored in the array it points to.

-

On input, nr points to the number of targets that may be stored in the array targets (and values). On output, nr points to the number of targets (and values) that were actually found, even if some of them couldn't be stored in the array. Targets that couldn't be stored are ignored, but the function still returns success (0). The caller may find out by comparing the value pointed by nr before and after the function call.

-

The returned targets should not be modified or freed, they belong to the topology.

-

Argument initiator is ignored if the attribute does not relate to a specific initiator (it does not have the flag HWLOC_MEMATTR_FLAG_NEED_INITIATOR). Otherwise initiator may be non NULL to report only targets that have a value for that initiator.

-

flags must be 0 for now.

-
Note
This function is meant for tools and debugging (listing internal information) rather than for application queries. Applications should rather select useful NUMA nodes with hwloc_get_local_numanode_objs() and then look at their attribute values.
-
-The initiator initiator should be of type HWLOC_LOCATION_TYPE_CPUSET when referring to accesses performed by CPU cores. HWLOC_LOCATION_TYPE_OBJECT is currently unused internally by hwloc, but users may for instance use it to provide custom information about host memory accesses performed by GPUs.
- -
-
- -

◆ hwloc_memattr_register()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_memattr_register (hwloc_topology_t topology,
const char * name,
unsigned long flags,
hwloc_memattr_id_t * id 
)
-
- -

Register a new memory attribute.

-

Add a specific memory attribute that is not defined in hwloc_memattr_id_e. Flags are a OR'ed set of hwloc_memattr_flag_e. It must contain at least one of HWLOC_MEMATTR_FLAG_HIGHER_FIRST or HWLOC_MEMATTR_FLAG_LOWER_FIRST.

- -
-
- -

◆ hwloc_memattr_set_value()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_memattr_set_value (hwloc_topology_t topology,
hwloc_memattr_id_t attribute,
hwloc_obj_t target_node,
struct hwloc_location * initiator,
unsigned long flags,
hwloc_uint64_t value 
)
-
- -

Set an attribute value for a specific target NUMA node.

-

If the attribute does not relate to a specific initiator (it does not have the flag HWLOC_MEMATTR_FLAG_NEED_INITIATOR), location initiator is ignored and may be NULL.

-

The initiator will be copied into the topology, the caller should free anything allocated to store the initiator, for instance the cpuset.

-

flags must be 0 for now.

-
Note
The initiator initiator should be of type HWLOC_LOCATION_TYPE_CPUSET when referring to accesses performed by CPU cores. HWLOC_LOCATION_TYPE_OBJECT is currently unused internally by hwloc, but users may for instance use it to provide custom information about host memory accesses performed by GPUs.
- -
-
-
- - - - - - - -
-
-Functions
-
-
Kinds of CPU cores
-
-
- - - - - - - - - - -

-Functions

int hwloc_cpukinds_get_nr (hwloc_topology_t topology, unsigned long flags)
 
int hwloc_cpukinds_get_by_cpuset (hwloc_topology_t topology, hwloc_const_bitmap_t cpuset, unsigned long flags)
 
int hwloc_cpukinds_get_info (hwloc_topology_t topology, unsigned kind_index, hwloc_bitmap_t cpuset, int *efficiency, unsigned *nr_infos, struct hwloc_info_s **infos, unsigned long flags)
 
int hwloc_cpukinds_register (hwloc_topology_t topology, hwloc_bitmap_t cpuset, int forced_efficiency, unsigned nr_infos, struct hwloc_info_s *infos, unsigned long flags)
 
-

Detailed Description

-

Platforms with heterogeneous CPUs may have some cores with different features or frequencies. This API exposes identical PUs in sets called CPU kinds. Each PU of the topology may only be in a single kind.

-

The number of kinds may be obtained with hwloc_cpukinds_get_nr(). If the platform is homogeneous, there may be a single kind with all PUs. If the platform or operating system does not expose any information about CPU cores, there may be no kind at all.

-

The index of the kind that describes a given CPU set (if any, and not partially) may be obtained with hwloc_cpukinds_get_by_cpuset().

-

From the index of a kind, it is possible to retrieve information with hwloc_cpukinds_get_info(): an abstracted efficiency value, and an array of info attributes (for instance the "CoreType" and "FrequencyMaxMHz", see CPU Kinds).

-

A higher efficiency value means greater intrinsic performance (and possibly less performance/power efficiency). Kinds with lower efficiency values are ranked first: Passing 0 as kind_index to hwloc_cpukinds_get_info() will return information about the CPU kind with lower performance but higher energy-efficiency. Higher kind_index values would rather return information about power-hungry high-performance cores.

-

When available, efficiency values are gathered from the operating system. If so, cpukind_efficiency is set in the struct hwloc_topology_discovery_support array. This is currently available on Windows 10, Mac OS X (Darwin), and on some Linux platforms where core "capacity" is exposed in sysfs.

-

If the operating system does not expose core efficiencies natively, hwloc tries to compute efficiencies by comparing CPU kinds using frequencies (on ARM), or core types and frequencies (on other architectures). The environment variable HWLOC_CPUKINDS_RANKING may be used to change this heuristics, see Environment Variables.

-

If hwloc fails to rank any kind, for instance because the operating system does not expose efficiencies and core frequencies, all kinds will have an unknown efficiency (-1), and they are not indexed/ordered in any specific way.

-

Function Documentation

- -

◆ hwloc_cpukinds_get_by_cpuset()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_cpukinds_get_by_cpuset (hwloc_topology_t topology,
hwloc_const_bitmap_t cpuset,
unsigned long flags 
)
-
- -

Get the index of the CPU kind that contains CPUs listed in cpuset.

-

flags must be 0 for now.

-
Returns
The index of the CPU kind (positive integer or 0) on success.
-
--1 with errno set to EXDEV if cpuset is only partially included in the some kind.
-
--1 with errno set to ENOENT if cpuset is not included in any kind, even partially.
-
--1 with errno set to EINVAL if parameters are invalid.
- -
-
- -

◆ hwloc_cpukinds_get_info()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_cpukinds_get_info (hwloc_topology_t topology,
unsigned kind_index,
hwloc_bitmap_t cpuset,
int * efficiency,
unsigned * nr_infos,
struct hwloc_info_s ** infos,
unsigned long flags 
)
-
- -

Get the CPU set and infos about a CPU kind in the topology.

-

kind_index identifies one kind of CPU between 0 and the number of kinds returned by hwloc_cpukinds_get_nr() minus 1.

-

If not NULL, the bitmap cpuset will be filled with the set of PUs of this kind.

-

The integer pointed by efficiency, if not NULL will, be filled with the ranking of this kind of CPU in term of efficiency (see above). It ranges from 0 to the number of kinds (as reported by hwloc_cpukinds_get_nr()) minus 1.

-

Kinds with lower efficiency are reported first.

-

If there is a single kind in the topology, its efficiency 0. If the efficiency of some kinds of cores is unknown, the efficiency of all kinds is set to -1, and kinds are reported in no specific order.

-

The array of info attributes (for instance the "CoreType", "FrequencyMaxMHz" or "FrequencyBaseMHz", see CPU Kinds) and its length are returned in infos or nr_infos. The array belongs to the topology, it should not be freed or modified.

-

If nr_infos or infos is NULL, no info is returned.

-

flags must be 0 for now.

-
Returns
0 on success.
-
--1 with errno set to ENOENT if kind_index does not match any CPU kind.
-
--1 with errno set to EINVAL if parameters are invalid.
- -
-
- -

◆ hwloc_cpukinds_get_nr()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_cpukinds_get_nr (hwloc_topology_t topology,
unsigned long flags 
)
-
- -

Get the number of different kinds of CPU cores in the topology.

-

flags must be 0 for now.

-
Returns
The number of CPU kinds (positive integer) on success.
-
-0 if no information about kinds was found.
-
--1 with errno set to EINVAL if flags is invalid.
- -
-
- -

◆ hwloc_cpukinds_register()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_cpukinds_register (hwloc_topology_t topology,
hwloc_bitmap_t cpuset,
int forced_efficiency,
unsigned nr_infos,
struct hwloc_info_s * infos,
unsigned long flags 
)
-
- -

Register a kind of CPU in the topology.

-

Mark the PUs listed in cpuset as being of the same kind with respect to the given attributes.

-

forced_efficiency should be -1 if unknown. Otherwise it is an abstracted efficiency value to enforce the ranking of all kinds if all of them have valid (and different) efficiencies.

-

The array infos of size nr_infos may be used to provide info names and values describing this kind of PUs.

-

flags must be 0 for now.

-

Parameters cpuset and infos will be duplicated internally, the caller is responsible for freeing them.

-

If cpuset overlaps with some existing kinds, those might get modified or split. For instance if existing kind A contains PUs 0 and 1, and one registers another kind for PU 1 and 2, there will be 3 resulting kinds: existing kind A is restricted to only PU 0; new kind B contains only PU 1 and combines information from A and from the newly-registered kind; new kind C contains only PU 2 and only gets information from the newly-registered kind.

-
Note
The efficiency forced_efficiency provided to this function may be different from the one reported later by hwloc_cpukinds_get_info() because hwloc will scale efficiency values down to between 0 and the number of kinds minus 1.
-
Returns
0 on success.
-
--1 with errno set to EINVAL if some parameters are invalid, for instance if cpuset is NULL or empty.
- -
-
-
- - - - - - - -
-
-Functions
-
-
Linux-specific helpers
-
-
- - - - - - - - - - -

-Functions

int hwloc_linux_set_tid_cpubind (hwloc_topology_t topology, pid_t tid, hwloc_const_cpuset_t set)
 
int hwloc_linux_get_tid_cpubind (hwloc_topology_t topology, pid_t tid, hwloc_cpuset_t set)
 
int hwloc_linux_get_tid_last_cpu_location (hwloc_topology_t topology, pid_t tid, hwloc_bitmap_t set)
 
int hwloc_linux_read_path_as_cpumask (const char *path, hwloc_bitmap_t set)
 
-

Detailed Description

-

This includes helpers for manipulating Linux kernel cpumap files, and hwloc equivalents of the Linux sched_setaffinity and sched_getaffinity system calls.

-

Function Documentation

- -

◆ hwloc_linux_get_tid_cpubind()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_linux_get_tid_cpubind (hwloc_topology_t topology,
pid_t tid,
hwloc_cpuset_t set 
)
-
- -

Get the current binding of thread tid.

-

The CPU-set set (previously allocated by the caller) is filled with the list of PUs which the thread was last bound to.

-

The behavior is exactly the same as the Linux sched_getaffinity system call, but uses a hwloc cpuset.

-
Note
This is equivalent to calling hwloc_get_proc_cpubind() with HWLOC_CPUBIND_THREAD as flags.
- -
-
- -

◆ hwloc_linux_get_tid_last_cpu_location()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_linux_get_tid_last_cpu_location (hwloc_topology_t topology,
pid_t tid,
hwloc_bitmap_t set 
)
-
- -

Get the last physical CPU where thread tid ran.

-

The CPU-set set (previously allocated by the caller) is filled with the PU which the thread last ran on.

-
Note
This is equivalent to calling hwloc_get_proc_last_cpu_location() with HWLOC_CPUBIND_THREAD as flags.
- -
-
- -

◆ hwloc_linux_read_path_as_cpumask()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_linux_read_path_as_cpumask (const char * path,
hwloc_bitmap_t set 
)
-
- -

Convert a linux kernel cpumask file path into a hwloc bitmap set.

-

Might be used when reading CPU set from sysfs attributes such as topology and caches for processors, or local_cpus for devices.

-
Note
This function ignores the HWLOC_FSROOT environment variable.
- -
-
- -

◆ hwloc_linux_set_tid_cpubind()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_linux_set_tid_cpubind (hwloc_topology_t topology,
pid_t tid,
hwloc_const_cpuset_t set 
)
-
- -

Bind a thread tid on cpus given in cpuset set.

-

The behavior is exactly the same as the Linux sched_setaffinity system call, but uses a hwloc cpuset.

-
Note
This is equivalent to calling hwloc_set_proc_cpubind() with HWLOC_CPUBIND_THREAD as flags.
- -
-
-
- - - - - - - -
-
-Functions
-
-
Interoperability with Linux libnuma unsigned long masks
-
-
- - - - - - - - - - -

-Functions

static int hwloc_cpuset_to_linux_libnuma_ulongs (hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, unsigned long *mask, unsigned long *maxnode)
 
static int hwloc_nodeset_to_linux_libnuma_ulongs (hwloc_topology_t topology, hwloc_const_nodeset_t nodeset, unsigned long *mask, unsigned long *maxnode)
 
static int hwloc_cpuset_from_linux_libnuma_ulongs (hwloc_topology_t topology, hwloc_cpuset_t cpuset, const unsigned long *mask, unsigned long maxnode)
 
static int hwloc_nodeset_from_linux_libnuma_ulongs (hwloc_topology_t topology, hwloc_nodeset_t nodeset, const unsigned long *mask, unsigned long maxnode)
 
-

Detailed Description

-

This interface helps converting between Linux libnuma unsigned long masks and hwloc cpusets and nodesets.

-
Note
Topology topology must match the current machine.
-
-The behavior of libnuma is undefined if the kernel is not NUMA-aware. (when CONFIG_NUMA is not set in the kernel configuration). This helper and libnuma may thus not be strictly compatible in this case, which may be detected by checking whether numa_available() returns -1.
-

Function Documentation

- -

◆ hwloc_cpuset_from_linux_libnuma_ulongs()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
static int hwloc_cpuset_from_linux_libnuma_ulongs (hwloc_topology_t topology,
hwloc_cpuset_t cpuset,
const unsigned long * mask,
unsigned long maxnode 
)
- 		-inlinestatic
-
- -

Convert the array of unsigned long mask into hwloc CPU set.

-

mask is a array of unsigned long that will be read. maxnode contains the maximal node number that may be read in mask.

-

This function may be used after calling get_mempolicy or any other function that takes an array of unsigned long as output parameter (and possibly a maximal node number as input parameter).

- -
-
- -

◆ hwloc_cpuset_to_linux_libnuma_ulongs()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
static int hwloc_cpuset_to_linux_libnuma_ulongs (hwloc_topology_t topology,
hwloc_const_cpuset_t cpuset,
unsigned long * mask,
unsigned long * maxnode 
)
- 		-inlinestatic
-
- -

Convert hwloc CPU set cpuset into the array of unsigned long mask.

-

mask is the array of unsigned long that will be filled. maxnode contains the maximal node number that may be stored in mask. maxnode will be set to the maximal node number that was found, plus one.

-

This function may be used before calling set_mempolicy, mbind, migrate_pages or any other function that takes an array of unsigned long and a maximal node number as input parameter.

- -
-
- -

◆ hwloc_nodeset_from_linux_libnuma_ulongs()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
static int hwloc_nodeset_from_linux_libnuma_ulongs (hwloc_topology_t topology,
hwloc_nodeset_t nodeset,
const unsigned long * mask,
unsigned long maxnode 
)
- 		-inlinestatic
-
- -

Convert the array of unsigned long mask into hwloc NUMA node set.

-

mask is a array of unsigned long that will be read. maxnode contains the maximal node number that may be read in mask.

-

This function may be used after calling get_mempolicy or any other function that takes an array of unsigned long as output parameter (and possibly a maximal node number as input parameter).

- -
-
- -

◆ hwloc_nodeset_to_linux_libnuma_ulongs()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
static int hwloc_nodeset_to_linux_libnuma_ulongs (hwloc_topology_t topology,
hwloc_const_nodeset_t nodeset,
unsigned long * mask,
unsigned long * maxnode 
)
- 		-inlinestatic
-
- -

Convert hwloc NUMA node set nodeset into the array of unsigned long mask.

-

mask is the array of unsigned long that will be filled. maxnode contains the maximal node number that may be stored in mask. maxnode will be set to the maximal node number that was found, plus one.

-

This function may be used before calling set_mempolicy, mbind, migrate_pages or any other function that takes an array of unsigned long and a maximal node number as input parameter.

- -
-
-
- - - - - - - -
-
-Functions
-
-
Interoperability with Linux libnuma bitmask
-
-
- - - - - - - - - - -

-Functions

static struct bitmask * hwloc_cpuset_to_linux_libnuma_bitmask (hwloc_topology_t topology, hwloc_const_cpuset_t cpuset)
 
static struct bitmask * hwloc_nodeset_to_linux_libnuma_bitmask (hwloc_topology_t topology, hwloc_const_nodeset_t nodeset)
 
static int hwloc_cpuset_from_linux_libnuma_bitmask (hwloc_topology_t topology, hwloc_cpuset_t cpuset, const struct bitmask *bitmask)
 
static int hwloc_nodeset_from_linux_libnuma_bitmask (hwloc_topology_t topology, hwloc_nodeset_t nodeset, const struct bitmask *bitmask)
 
-

Detailed Description

-

This interface helps converting between Linux libnuma bitmasks and hwloc cpusets and nodesets.

-
Note
Topology topology must match the current machine.
-
-The behavior of libnuma is undefined if the kernel is not NUMA-aware. (when CONFIG_NUMA is not set in the kernel configuration). This helper and libnuma may thus not be strictly compatible in this case, which may be detected by checking whether numa_available() returns -1.
-

Function Documentation

- -

◆ hwloc_cpuset_from_linux_libnuma_bitmask()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - -
static int hwloc_cpuset_from_linux_libnuma_bitmask (hwloc_topology_t topology,
hwloc_cpuset_t cpuset,
const struct bitmask * bitmask 
)
- 		-inlinestatic
-
- -

Convert libnuma bitmask bitmask into hwloc CPU set cpuset.

-

This function may be used after calling many numa_ functions that use a struct bitmask as an output parameter.

- -
-
- -

◆ hwloc_cpuset_to_linux_libnuma_bitmask()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static struct bitmask * hwloc_cpuset_to_linux_libnuma_bitmask (hwloc_topology_t topology,
hwloc_const_cpuset_t cpuset 
)
- 		-inlinestatic
-
- -

Convert hwloc CPU set cpuset into the returned libnuma bitmask.

-

The returned bitmask should later be freed with numa_bitmask_free.

-

This function may be used before calling many numa_ functions that use a struct bitmask as an input parameter.

-
Returns
newly allocated struct bitmask.
- -
-
- -

◆ hwloc_nodeset_from_linux_libnuma_bitmask()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - -
static int hwloc_nodeset_from_linux_libnuma_bitmask (hwloc_topology_t topology,
hwloc_nodeset_t nodeset,
const struct bitmask * bitmask 
)
- 		-inlinestatic
-
- -

Convert libnuma bitmask bitmask into hwloc NUMA node set nodeset.

-

This function may be used after calling many numa_ functions that use a struct bitmask as an output parameter.

- -
-
- -

◆ hwloc_nodeset_to_linux_libnuma_bitmask()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static struct bitmask * hwloc_nodeset_to_linux_libnuma_bitmask (hwloc_topology_t topology,
hwloc_const_nodeset_t nodeset 
)
- 		-inlinestatic
-
- -

Convert hwloc NUMA node set nodeset into the returned libnuma bitmask.

-

The returned bitmask should later be freed with numa_bitmask_free.

-

This function may be used before calling many numa_ functions that use a struct bitmask as an input parameter.

-
Returns
newly allocated struct bitmask.
- -
-
-
- - - - - - - -
-
-Functions
-
-
Windows-specific helpers
-
-
- - - - - - -

-Functions

int hwloc_windows_get_nr_processor_groups (hwloc_topology_t topology, unsigned long flags)
 
int hwloc_windows_get_processor_group_cpuset (hwloc_topology_t topology, unsigned pg_index, hwloc_cpuset_t cpuset, unsigned long flags)
 
-

Detailed Description

-

These functions query Windows processor groups. These groups partition the operating system into virtual sets of up to 64 neighbor PUs. Threads and processes may only be bound inside a single group. Although Windows processor groups may be exposed in the hwloc hierarchy as hwloc Groups, they are also often merged into existing hwloc objects such as NUMA nodes or Packages. This API provides explicit information about Windows processor groups so that applications know whether binding to a large set of PUs may fail because it spans over multiple Windows processor groups.

-

Function Documentation

- -

◆ hwloc_windows_get_nr_processor_groups()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_windows_get_nr_processor_groups (hwloc_topology_t topology,
unsigned long flags 
)
-
- -

Get the number of Windows processor groups.

-

flags must be 0 for now.

-
Returns
at least 1 on success.
-
--1 on error, for instance if the topology does not match the current system (e.g. loaded from another machine through XML).
- -
-
- -

◆ hwloc_windows_get_processor_group_cpuset()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_windows_get_processor_group_cpuset (hwloc_topology_t topology,
unsigned pg_index,
hwloc_cpuset_t cpuset,
unsigned long flags 
)
-
- -

Get the CPU-set of a Windows processor group.

-

Get the set of PU included in the processor group specified by pg_index. pg_index must be between 0 and the value returned by hwloc_windows_get_nr_processor_groups() minus 1.

-

flags must be 0 for now.

-
Returns
0 on success.
-
--1 on error, for instance if pg_index is invalid, or if the topology does not match the current system (e.g. loaded from another machine through XML).
- -
-
-
- - - - - - - -
-
-Functions
-
-
Interoperability with glibc sched affinity
-
-
- - - - - - -

-Functions

static int hwloc_cpuset_to_glibc_sched_affinity (hwloc_topology_t topology, hwloc_const_cpuset_t hwlocset, cpu_set_t *schedset, size_t schedsetsize)
 
static int hwloc_cpuset_from_glibc_sched_affinity (hwloc_topology_t topology, hwloc_cpuset_t hwlocset, const cpu_set_t *schedset, size_t schedsetsize)
 
-

Detailed Description

-

This interface offers ways to convert between hwloc cpusets and glibc cpusets such as those manipulated by sched_getaffinity() or pthread_attr_setaffinity_np().

-
Note
Topology topology must match the current machine.
-

Function Documentation

- -

◆ hwloc_cpuset_from_glibc_sched_affinity()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
static int hwloc_cpuset_from_glibc_sched_affinity (hwloc_topology_t topology,
hwloc_cpuset_t hwlocset,
const cpu_set_t * schedset,
size_t schedsetsize 
)
- 		-inlinestatic
-
- -

Convert glibc sched affinity CPU set schedset into hwloc CPU set.

-

This function may be used before calling sched_setaffinity or any other function that takes a cpu_set_t as input parameter.

-

schedsetsize should be sizeof(cpu_set_t) unless schedset was dynamically allocated with CPU_ALLOC

- -
-
- -

◆ hwloc_cpuset_to_glibc_sched_affinity()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
static int hwloc_cpuset_to_glibc_sched_affinity (hwloc_topology_t topology,
hwloc_const_cpuset_t hwlocset,
cpu_set_t * schedset,
size_t schedsetsize 
)
- 		-inlinestatic
-
- -

Convert hwloc CPU set toposet into glibc sched affinity CPU set schedset.

-

This function may be used before calling sched_setaffinity or any other function that takes a cpu_set_t as input parameter.

-

schedsetsize should be sizeof(cpu_set_t) unless schedset was dynamically allocated with CPU_ALLOC

- -
-
-
- - - - - - - -
-
-Functions
-
-
Interoperability with OpenCL
-
-
- - - - - - - - - - -

-Functions

static int hwloc_opencl_get_device_pci_busid (cl_device_id device, unsigned *domain, unsigned *bus, unsigned *dev, unsigned *func)
 
static int hwloc_opencl_get_device_cpuset (hwloc_topology_t topology, cl_device_id device, hwloc_cpuset_t set)
 
static hwloc_obj_t hwloc_opencl_get_device_osdev_by_index (hwloc_topology_t topology, unsigned platform_index, unsigned device_index)
 
static hwloc_obj_t hwloc_opencl_get_device_osdev (hwloc_topology_t topology, cl_device_id device)
 
-

Detailed Description

-

This interface offers ways to retrieve topology information about OpenCL devices.

-

Only AMD and NVIDIA OpenCL implementations currently offer useful locality information about their devices.

-

Function Documentation

- -

◆ hwloc_opencl_get_device_cpuset()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - -
static int hwloc_opencl_get_device_cpuset (hwloc_topology_t topology,
cl_device_id device,
hwloc_cpuset_t set 
)
- 		-inlinestatic
-
- -

Get the CPU set of processors that are physically close to OpenCL device device.

-

Store in set the CPU-set describing the locality of the OpenCL device device.

-

Topology topology and device device must match the local machine. I/O devices detection and the OpenCL component are not needed in the topology.

-

The function only returns the locality of the device. If more information about the device is needed, OS objects should be used instead, see hwloc_opencl_get_device_osdev() and hwloc_opencl_get_device_osdev_by_index().

-

This function is currently only implemented in a meaningful way for Linux with the AMD or NVIDIA OpenCL implementation; other systems will simply get a full cpuset.

- -
-
- -

◆ hwloc_opencl_get_device_osdev()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_opencl_get_device_osdev (hwloc_topology_t topology,
cl_device_id device 
)
- 		-inlinestatic
-
- -

Get the hwloc OS device object corresponding to OpenCL device deviceX.

-
Returns
The hwloc OS device object corresponding to the given OpenCL device device.
-
-NULL if none could be found, for instance if required OpenCL attributes are not available.
-

This function currently only works on AMD and NVIDIA OpenCL devices that support relevant OpenCL extensions. hwloc_opencl_get_device_osdev_by_index() should be preferred whenever possible, i.e. when platform and device index are known.

-

Topology topology and device device must match the local machine. I/O devices detection and the OpenCL component must be enabled in the topology. If not, the locality of the object may still be found using hwloc_opencl_get_device_cpuset().

-
Note
This function cannot work if PCI devices are filtered out.
-
-The corresponding hwloc PCI device may be found by looking at the result parent pointer (unless PCI devices are filtered out).
- -
-
- -

◆ hwloc_opencl_get_device_osdev_by_index()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_opencl_get_device_osdev_by_index (hwloc_topology_t topology,
unsigned platform_index,
unsigned device_index 
)
- 		-inlinestatic
-
- -

Get the hwloc OS device object corresponding to the OpenCL device for the given indexes.

-
Returns
The hwloc OS device object describing the OpenCL device whose platform index is platform_index, and whose device index within this platform if device_index.
-
-NULL if there is none.
-

The topology topology does not necessarily have to match the current machine. For instance the topology may be an XML import of a remote host. I/O devices detection and the OpenCL component must be enabled in the topology.

-
Note
The corresponding PCI device object can be obtained by looking at the OS device parent object (unless PCI devices are filtered out).
- -
-
- -

◆ hwloc_opencl_get_device_pci_busid()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
static int hwloc_opencl_get_device_pci_busid (cl_device_id device,
unsigned * domain,
unsigned * bus,
unsigned * dev,
unsigned * func 
)
- 		-inlinestatic
-
- -

Return the domain, bus and device IDs of the OpenCL device device.

-

Device device must match the local machine.

- -
-
-
- - - - - - - -
-
-Functions
-
-
Interoperability with the CUDA Driver API
-
-
- - - - - - - - - - - - -

-Functions

static int hwloc_cuda_get_device_pci_ids (hwloc_topology_t topology, CUdevice cudevice, int *domain, int *bus, int *dev)
 
static int hwloc_cuda_get_device_cpuset (hwloc_topology_t topology, CUdevice cudevice, hwloc_cpuset_t set)
 
static hwloc_obj_t hwloc_cuda_get_device_pcidev (hwloc_topology_t topology, CUdevice cudevice)
 
static hwloc_obj_t hwloc_cuda_get_device_osdev (hwloc_topology_t topology, CUdevice cudevice)
 
static hwloc_obj_t hwloc_cuda_get_device_osdev_by_index (hwloc_topology_t topology, unsigned idx)
 
-

Detailed Description

-

This interface offers ways to retrieve topology information about CUDA devices when using the CUDA Driver API.

-

Function Documentation

- -

◆ hwloc_cuda_get_device_cpuset()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - -
static int hwloc_cuda_get_device_cpuset (hwloc_topology_t topology,
CUdevice cudevice,
hwloc_cpuset_t set 
)
- 		-inlinestatic
-
- -

Get the CPU set of processors that are physically close to device cudevice.

-

Store in set the CPU-set describing the locality of the CUDA device cudevice.

-

Topology topology and device cudevice must match the local machine. I/O devices detection and the CUDA component are not needed in the topology.

-

The function only returns the locality of the device. If more information about the device is needed, OS objects should be used instead, see hwloc_cuda_get_device_osdev() and hwloc_cuda_get_device_osdev_by_index().

-

This function is currently only implemented in a meaningful way for Linux; other systems will simply get a full cpuset.

- -
-
- -

◆ hwloc_cuda_get_device_osdev()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_cuda_get_device_osdev (hwloc_topology_t topology,
CUdevice cudevice 
)
- 		-inlinestatic
-
- -

Get the hwloc OS device object corresponding to CUDA device cudevice.

-
Returns
The hwloc OS device object that describes the given CUDA device cudevice.
-
-NULL if none could be found.
-

Topology topology and device cudevice must match the local machine. I/O devices detection and the CUDA component must be enabled in the topology. If not, the locality of the object may still be found using hwloc_cuda_get_device_cpuset().

-
Note
This function cannot work if PCI devices are filtered out.
-
-The corresponding hwloc PCI device may be found by looking at the result parent pointer (unless PCI devices are filtered out).
- -
-
- -

◆ hwloc_cuda_get_device_osdev_by_index()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_cuda_get_device_osdev_by_index (hwloc_topology_t topology,
unsigned idx 
)
- 		-inlinestatic
-
- -

Get the hwloc OS device object corresponding to the CUDA device whose index is idx.

-
Returns
The hwloc OS device object describing the CUDA device whose index is idx.
-
-NULL if none could be found.
-

The topology topology does not necessarily have to match the current machine. For instance the topology may be an XML import of a remote host. I/O devices detection and the CUDA component must be enabled in the topology.

-
Note
The corresponding PCI device object can be obtained by looking at the OS device parent object (unless PCI devices are filtered out).
-
-This function is identical to hwloc_cudart_get_device_osdev_by_index().
- -
-
- -

◆ hwloc_cuda_get_device_pci_ids()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
static int hwloc_cuda_get_device_pci_ids (hwloc_topology_t topology,
CUdevice cudevice,
int * domain,
int * bus,
int * dev 
)
- 		-inlinestatic
-
- -

Return the domain, bus and device IDs of the CUDA device cudevice.

-

Device cudevice must match the local machine.

- -
-
- -

◆ hwloc_cuda_get_device_pcidev()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_cuda_get_device_pcidev (hwloc_topology_t topology,
CUdevice cudevice 
)
- 		-inlinestatic
-
- -

Get the hwloc PCI device object corresponding to the CUDA device cudevice.

-
Returns
The hwloc PCI device object describing the CUDA device cudevice.
-
-NULL if none could be found.
-

Topology topology and device cudevice must match the local machine. I/O devices detection must be enabled in topology topology. The CUDA component is not needed in the topology.

- -
-
-
- - - - - - - -
-
-Functions
-
-
Interoperability with the CUDA Runtime API
-
-
- - - - - - - - - - -

-Functions

static int hwloc_cudart_get_device_pci_ids (hwloc_topology_t topology, int idx, int *domain, int *bus, int *dev)
 
static int hwloc_cudart_get_device_cpuset (hwloc_topology_t topology, int idx, hwloc_cpuset_t set)
 
static hwloc_obj_t hwloc_cudart_get_device_pcidev (hwloc_topology_t topology, int idx)
 
static hwloc_obj_t hwloc_cudart_get_device_osdev_by_index (hwloc_topology_t topology, unsigned idx)
 
-

Detailed Description

-

This interface offers ways to retrieve topology information about CUDA devices when using the CUDA Runtime API.

-

Function Documentation

- -

◆ hwloc_cudart_get_device_cpuset()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - -
static int hwloc_cudart_get_device_cpuset (hwloc_topology_t topology,
int idx,
hwloc_cpuset_t set 
)
- 		-inlinestatic
-
- -

Get the CPU set of processors that are physically close to device idx.

-

Store in set the CPU-set describing the locality of the CUDA device whose index is idx.

-

Topology topology and device idx must match the local machine. I/O devices detection and the CUDA component are not needed in the topology.

-

The function only returns the locality of the device. If more information about the device is needed, OS objects should be used instead, see hwloc_cudart_get_device_osdev_by_index().

-

This function is currently only implemented in a meaningful way for Linux; other systems will simply get a full cpuset.

- -
-
- -

◆ hwloc_cudart_get_device_osdev_by_index()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_cudart_get_device_osdev_by_index (hwloc_topology_t topology,
unsigned idx 
)
- 		-inlinestatic
-
- -

Get the hwloc OS device object corresponding to the CUDA device whose index is idx.

-
Returns
The hwloc OS device object describing the CUDA device whose index is idx.
-
-NULL if none could be found.
-

The topology topology does not necessarily have to match the current machine. For instance the topology may be an XML import of a remote host. I/O devices detection and the CUDA component must be enabled in the topology. If not, the locality of the object may still be found using hwloc_cudart_get_device_cpuset().

-
Note
The corresponding PCI device object can be obtained by looking at the OS device parent object (unless PCI devices are filtered out).
-
-This function is identical to hwloc_cuda_get_device_osdev_by_index().
- -
-
- -

◆ hwloc_cudart_get_device_pci_ids()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
static int hwloc_cudart_get_device_pci_ids (hwloc_topology_t topology,
int idx,
int * domain,
int * bus,
int * dev 
)
- 		-inlinestatic
-
- -

Return the domain, bus and device IDs of the CUDA device whose index is idx.

-

Device index idx must match the local machine.

- -
-
- -

◆ hwloc_cudart_get_device_pcidev()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_cudart_get_device_pcidev (hwloc_topology_t topology,
int idx 
)
- 		-inlinestatic
-
- -

Get the hwloc PCI device object corresponding to the CUDA device whose index is idx.

-
Returns
The hwloc PCI device object describing the CUDA device whose index is idx.
-
-NULL if none could be found.
-

Topology topology and device idx must match the local machine. I/O devices detection must be enabled in topology topology. The CUDA component is not needed in the topology.

- -
-
-
- - - - - - - -
-
-Functions
-
-
Interoperability with the NVIDIA Management Library
-
-
- - - - - - - - -

-Functions

static int hwloc_nvml_get_device_cpuset (hwloc_topology_t topology, nvmlDevice_t device, hwloc_cpuset_t set)
 
static hwloc_obj_t hwloc_nvml_get_device_osdev_by_index (hwloc_topology_t topology, unsigned idx)
 
static hwloc_obj_t hwloc_nvml_get_device_osdev (hwloc_topology_t topology, nvmlDevice_t device)
 
-

Detailed Description

-

This interface offers ways to retrieve topology information about devices managed by the NVIDIA Management Library (NVML).

-

Function Documentation

- -

◆ hwloc_nvml_get_device_cpuset()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - -
static int hwloc_nvml_get_device_cpuset (hwloc_topology_t topology,
nvmlDevice_t device,
hwloc_cpuset_t set 
)
- 		-inlinestatic
-
- -

Get the CPU set of processors that are physically close to NVML device device.

-

Store in set the CPU-set describing the locality of the NVML device device.

-

Topology topology and device device must match the local machine. I/O devices detection and the NVML component are not needed in the topology.

-

The function only returns the locality of the device. If more information about the device is needed, OS objects should be used instead, see hwloc_nvml_get_device_osdev() and hwloc_nvml_get_device_osdev_by_index().

-

This function is currently only implemented in a meaningful way for Linux; other systems will simply get a full cpuset.

- -
-
- -

◆ hwloc_nvml_get_device_osdev()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_nvml_get_device_osdev (hwloc_topology_t topology,
nvmlDevice_t device 
)
- 		-inlinestatic
-
- -

Get the hwloc OS device object corresponding to NVML device device.

-
Returns
The hwloc OS device object that describes the given NVML device device.
-
-NULL if none could be found.
-

Topology topology and device device must match the local machine. I/O devices detection and the NVML component must be enabled in the topology. If not, the locality of the object may still be found using hwloc_nvml_get_device_cpuset().

-
Note
The corresponding hwloc PCI device may be found by looking at the result parent pointer (unless PCI devices are filtered out).
- -
-
- -

◆ hwloc_nvml_get_device_osdev_by_index()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_nvml_get_device_osdev_by_index (hwloc_topology_t topology,
unsigned idx 
)
- 		-inlinestatic
-
- -

Get the hwloc OS device object corresponding to the NVML device whose index is idx.

-
Returns
The hwloc OS device object describing the NVML device whose index is idx.
-
-NULL if none could be found.
-

The topology topology does not necessarily have to match the current machine. For instance the topology may be an XML import of a remote host. I/O devices detection and the NVML component must be enabled in the topology.

-
Note
The corresponding PCI device object can be obtained by looking at the OS device parent object (unless PCI devices are filtered out).
- -
-
-
- - - - - - - -
-
-Functions
-
-
Interoperability with the ROCm SMI Management Library
-
-
- - - - - - - - -

-Functions

static int hwloc_rsmi_get_device_cpuset (hwloc_topology_t topology, uint32_t dv_ind, hwloc_cpuset_t set)
 
static hwloc_obj_t hwloc_rsmi_get_device_osdev_by_index (hwloc_topology_t topology, uint32_t dv_ind)
 
static hwloc_obj_t hwloc_rsmi_get_device_osdev (hwloc_topology_t topology, uint32_t dv_ind)
 
-

Detailed Description

-

This interface offers ways to retrieve topology information about devices managed by the ROCm SMI Management Library.

-

Function Documentation

- -

◆ hwloc_rsmi_get_device_cpuset()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - -
static int hwloc_rsmi_get_device_cpuset (hwloc_topology_t topology,
uint32_t dv_ind,
hwloc_cpuset_t set 
)
- 		-inlinestatic
-
- -

Get the CPU set of logical processors that are physically close to AMD GPU device whose index is dv_ind.

-

Store in set the CPU-set describing the locality of the AMD GPU device whose index is dv_ind.

-

Topology topology and device dv_ind must match the local machine. I/O devices detection and the ROCm SMI component are not needed in the topology.

-

The function only returns the locality of the device. If more information about the device is needed, OS objects should be used instead, see hwloc_rsmi_get_device_osdev() and hwloc_rsmi_get_device_osdev_by_index().

-

This function is currently only implemented in a meaningful way for Linux; other systems will simply get a full cpuset.

- -
-
- -

◆ hwloc_rsmi_get_device_osdev()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_rsmi_get_device_osdev (hwloc_topology_t topology,
uint32_t dv_ind 
)
- 		-inlinestatic
-
- -

Get the hwloc OS device object corresponding to AMD GPU device, whose index is dv_ind.

-
Returns
The hwloc OS device object that describes the given AMD GPU, whose index is dv_ind.
-
-NULL if none could be found.
-

Topology topology and device dv_ind must match the local machine. I/O devices detection and the ROCm SMI component must be enabled in the topology. If not, the locality of the object may still be found using hwloc_rsmi_get_device_cpuset().

-
Note
The corresponding hwloc PCI device may be found by looking at the result parent pointer (unless PCI devices are filtered out).
- -
-
- -

◆ hwloc_rsmi_get_device_osdev_by_index()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_rsmi_get_device_osdev_by_index (hwloc_topology_t topology,
uint32_t dv_ind 
)
- 		-inlinestatic
-
- -

Get the hwloc OS device object corresponding to the AMD GPU device whose index is dv_ind.

-
Returns
The hwloc OS device object describing the AMD GPU device whose index is dv_ind.
-
-NULL if none could be found.
-

The topology topology does not necessarily have to match the current machine. For instance the topology may be an XML import of a remote host. I/O devices detection and the ROCm SMI component must be enabled in the topology.

-
Note
The corresponding PCI device object can be obtained by looking at the OS device parent object (unless PCI devices are filtered out).
- -
-
-
- - - - - - - -
-
-Functions
-
-
Interoperability with the oneAPI Level Zero interface.
-
-
- - - - - - -

-Functions

static int hwloc_levelzero_get_device_cpuset (hwloc_topology_t topology, ze_device_handle_t device, hwloc_cpuset_t set)
 
static hwloc_obj_t hwloc_levelzero_get_device_osdev (hwloc_topology_t topology, ze_device_handle_t device)
 
-

Detailed Description

-

This interface offers ways to retrieve topology information about devices managed by the Level Zero API.

-

Function Documentation

- -

◆ hwloc_levelzero_get_device_cpuset()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - -
static int hwloc_levelzero_get_device_cpuset (hwloc_topology_t topology,
ze_device_handle_t device,
hwloc_cpuset_t set 
)
- 		-inlinestatic
-
- -

Get the CPU set of logical processors that are physically close to the Level Zero device device.

-

Store in set the CPU-set describing the locality of the Level Zero device device.

-

Topology topology and device device must match the local machine. The Level Zero must have been initialized with Sysman enabled (ZES_ENABLE_SYSMAN=1 in the environment). I/O devices detection and the Level Zero component are not needed in the topology.

-

The function only returns the locality of the device. If more information about the device is needed, OS objects should be used instead, see hwloc_levelzero_get_device_osdev().

-

This function is currently only implemented in a meaningful way for Linux; other systems will simply get a full cpuset.

- -
-
- -

◆ hwloc_levelzero_get_device_osdev()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_levelzero_get_device_osdev (hwloc_topology_t topology,
ze_device_handle_t device 
)
- 		-inlinestatic
-
- -

Get the hwloc OS device object corresponding to Level Zero device device.

-
Returns
The hwloc OS device object that describes the given Level Zero device device.
-
-NULL if none could be found.
-

Topology topology and device dv_ind must match the local machine. I/O devices detection and the Level Zero component must be enabled in the topology. If not, the locality of the object may still be found using hwloc_levelzero_get_device_cpuset().

-
Note
The corresponding hwloc PCI device may be found by looking at the result parent pointer (unless PCI devices are filtered out).
- -
-
-
- - - - - - - -
-
-Functions
-
-
Interoperability with OpenGL displays
-
-
- - - - - - - - -

-Functions

static hwloc_obj_t hwloc_gl_get_display_osdev_by_port_device (hwloc_topology_t topology, unsigned port, unsigned device)
 
static hwloc_obj_t hwloc_gl_get_display_osdev_by_name (hwloc_topology_t topology, const char *name)
 
static int hwloc_gl_get_display_by_osdev (hwloc_topology_t topology, hwloc_obj_t osdev, unsigned *port, unsigned *device)
 
-

Detailed Description

-

This interface offers ways to retrieve topology information about OpenGL displays.

-

Only the NVIDIA display locality information is currently available, using the NV-CONTROL X11 extension and the NVCtrl library.

-

Function Documentation

- -

◆ hwloc_gl_get_display_by_osdev()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
static int hwloc_gl_get_display_by_osdev (hwloc_topology_t topology,
hwloc_obj_t osdev,
unsigned * port,
unsigned * device 
)
- 		-inlinestatic
-
- -

Get the OpenGL display port and device corresponding to the given hwloc OS object.

-

Retrieves the OpenGL display port (server) in port and device (screen) in screen that correspond to the given hwloc OS device object.

-
Returns
-1 if none could be found.
-

The topology topology does not necessarily have to match the current machine. For instance the topology may be an XML import of a remote host. I/O devices detection and the GL component must be enabled in the topology.

- -
-
- -

◆ hwloc_gl_get_display_osdev_by_name()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_gl_get_display_osdev_by_name (hwloc_topology_t topology,
const char * name 
)
- 		-inlinestatic
-
- -

Get the hwloc OS device object corresponding to the OpenGL display given by name.

-
Returns
The hwloc OS device object describing the OpenGL display whose name is name, built as ":port.device" such as ":0.0" .
-
-NULL if none could be found.
-

The topology topology does not necessarily have to match the current machine. For instance the topology may be an XML import of a remote host. I/O devices detection and the GL component must be enabled in the topology.

-
Note
The corresponding PCI device object can be obtained by looking at the OS device parent object (unless PCI devices are filtered out).
- -
-
- -

◆ hwloc_gl_get_display_osdev_by_port_device()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_gl_get_display_osdev_by_port_device (hwloc_topology_t topology,
unsigned port,
unsigned device 
)
- 		-inlinestatic
-
- -

Get the hwloc OS device object corresponding to the OpenGL display given by port and device index.

-
Returns
The hwloc OS device object describing the OpenGL display whose port (server) is port and device (screen) is device.
-
-NULL if none could be found.
-

The topology topology does not necessarily have to match the current machine. For instance the topology may be an XML import of a remote host. I/O devices detection and the GL component must be enabled in the topology.

-
Note
The corresponding PCI device object can be obtained by looking at the OS device parent object (unless PCI devices are filtered out).
- -
-
-
- - - - - - - -
-
-Functions
-
-
Interoperability with OpenFabrics
-
-
- - - - - - - - -

-Functions

static int hwloc_ibv_get_device_cpuset (hwloc_topology_t topology, struct ibv_device *ibdev, hwloc_cpuset_t set)
 
static hwloc_obj_t hwloc_ibv_get_device_osdev_by_name (hwloc_topology_t topology, const char *ibname)
 
static hwloc_obj_t hwloc_ibv_get_device_osdev (hwloc_topology_t topology, struct ibv_device *ibdev)
 
-

Detailed Description

-

This interface offers ways to retrieve topology information about OpenFabrics devices (InfiniBand, Omni-Path, usNIC, etc).

-

Function Documentation

- -

◆ hwloc_ibv_get_device_cpuset()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - -
static int hwloc_ibv_get_device_cpuset (hwloc_topology_t topology,
struct ibv_device * ibdev,
hwloc_cpuset_t set 
)
- 		-inlinestatic
-
- -

Get the CPU set of processors that are physically close to device ibdev.

-

Store in set the CPU-set describing the locality of the OpenFabrics device ibdev (InfiniBand, etc).

-

Topology topology and device ibdev must match the local machine. I/O devices detection is not needed in the topology.

-

The function only returns the locality of the device. If more information about the device is needed, OS objects should be used instead, see hwloc_ibv_get_device_osdev() and hwloc_ibv_get_device_osdev_by_name().

-

This function is currently only implemented in a meaningful way for Linux; other systems will simply get a full cpuset.

- -
-
- -

◆ hwloc_ibv_get_device_osdev()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_ibv_get_device_osdev (hwloc_topology_t topology,
struct ibv_device * ibdev 
)
- 		-inlinestatic
-
- -

Get the hwloc OS device object corresponding to the OpenFabrics device ibdev.

-
Returns
The hwloc OS device object describing the OpenFabrics device ibdev (InfiniBand, etc).
-
-NULL if none could be found.
-

Topology topology and device ibdev must match the local machine. I/O devices detection must be enabled in the topology. If not, the locality of the object may still be found using hwloc_ibv_get_device_cpuset().

-
Note
The corresponding PCI device object can be obtained by looking at the OS device parent object.
- -
-
- -

◆ hwloc_ibv_get_device_osdev_by_name()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static hwloc_obj_t hwloc_ibv_get_device_osdev_by_name (hwloc_topology_t topology,
const char * ibname 
)
- 		-inlinestatic
-
- -

Get the hwloc OS device object corresponding to the OpenFabrics device named ibname.

-
Returns
The hwloc OS device object describing the OpenFabrics device (InfiniBand, Omni-Path, usNIC, etc) whose name is ibname (mlx5_0, hfi1_0, usnic_0, qib0, etc).
-
-NULL if none could be found.
-

The name ibname is usually obtained from ibv_get_device_name().

-

The topology topology does not necessarily have to match the current machine. For instance the topology may be an XML import of a remote host. I/O devices detection must be enabled in the topology.

-
Note
The corresponding PCI device object can be obtained by looking at the OS device parent object.
- -
-
-
- - - - - - - -
-
-Data Structures | -Typedefs | -Enumerations | -Functions
-
-
Topology differences
-
-
- - - - - - -

-Data Structures

union  hwloc_topology_diff_obj_attr_u
 
union  hwloc_topology_diff_u
 
- - - - - - - -

-Typedefs

typedef enum hwloc_topology_diff_obj_attr_type_e hwloc_topology_diff_obj_attr_type_t
 
typedef enum hwloc_topology_diff_type_e hwloc_topology_diff_type_t
 
typedef union hwloc_topology_diff_u * hwloc_topology_diff_t
 
- - - - - - - -

-Enumerations

enum  hwloc_topology_diff_obj_attr_type_e { HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_SIZE -, HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_NAME -, HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_INFO - }
 
enum  hwloc_topology_diff_type_e { HWLOC_TOPOLOGY_DIFF_OBJ_ATTR -, HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX - }
 
enum  hwloc_topology_diff_apply_flags_e { HWLOC_TOPOLOGY_DIFF_APPLY_REVERSE - }
 
- - - - - - - - - - - - - - - -

-Functions

int hwloc_topology_diff_build (hwloc_topology_t topology, hwloc_topology_t newtopology, unsigned long flags, hwloc_topology_diff_t *diff)
 
int hwloc_topology_diff_apply (hwloc_topology_t topology, hwloc_topology_diff_t diff, unsigned long flags)
 
int hwloc_topology_diff_destroy (hwloc_topology_diff_t diff)
 
int hwloc_topology_diff_load_xml (const char *xmlpath, hwloc_topology_diff_t *diff, char **refname)
 
int hwloc_topology_diff_export_xml (hwloc_topology_diff_t diff, const char *refname, const char *xmlpath)
 
int hwloc_topology_diff_load_xmlbuffer (const char *xmlbuffer, int buflen, hwloc_topology_diff_t *diff, char **refname)
 
int hwloc_topology_diff_export_xmlbuffer (hwloc_topology_diff_t diff, const char *refname, char **xmlbuffer, int *buflen)
 
-

Detailed Description

-

Applications that manipulate many similar topologies, for instance one for each node of a homogeneous cluster, may want to compress topologies to reduce the memory footprint.

-

This file offers a way to manipulate the difference between topologies and export/import it to/from XML. Compression may therefore be achieved by storing one topology entirely while the others are only described by their differences with the former. The actual topology can be reconstructed when actually needed by applying the precomputed difference to the reference topology.

-

This interface targets very similar nodes. Only very simple differences between topologies are actually supported, for instance a change in the memory size, the name of the object, or some info attribute. More complex differences such as adding or removing objects cannot be represented in the difference structures and therefore return errors. Differences between object sets or topology-wide allowed sets, cannot be represented either.

-

It means that there is no need to apply the difference when looking at the tree organization (how many levels, how many objects per level, what kind of objects, CPU and node sets, etc) and when binding to objects. However the difference must be applied when looking at object attributes such as the name, the memory size or info attributes.

-

Typedef Documentation

- -

◆ hwloc_topology_diff_obj_attr_type_t

- -
-
- - - - -
typedef enum hwloc_topology_diff_obj_attr_type_e hwloc_topology_diff_obj_attr_type_t
-
- -

Type of one object attribute difference.

- -
-
- -

◆ hwloc_topology_diff_t

- -
-
- - - - -
typedef union hwloc_topology_diff_u * hwloc_topology_diff_t
-
- -

One element of a difference list between two topologies.

- -
-
- -

◆ hwloc_topology_diff_type_t

- -
-
- - - - -
typedef enum hwloc_topology_diff_type_e hwloc_topology_diff_type_t
-
- -

Type of one element of a difference list.

- -
-
-

Enumeration Type Documentation

- -

◆ hwloc_topology_diff_apply_flags_e

- -
-
- - - - -
enum hwloc_topology_diff_apply_flags_e
-
- -

Flags to be given to hwloc_topology_diff_apply().

- - -
Enumerator
HWLOC_TOPOLOGY_DIFF_APPLY_REVERSE 

Apply topology diff in reverse direction.

-
- -
-
- -

◆ hwloc_topology_diff_obj_attr_type_e

- -
-
- - - - -
enum hwloc_topology_diff_obj_attr_type_e
-
- -

Type of one object attribute difference.

- - - - -
Enumerator
HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_SIZE 

The object local memory is modified. The union is a hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s (and the index field is ignored).

-
HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_NAME 

The object name is modified. The union is a hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s (and the name field is ignored).

-
HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_INFO 

the value of an info attribute is modified. The union is a hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s.

-
- -
-
- -

◆ hwloc_topology_diff_type_e

- -
-
- - - - -
enum hwloc_topology_diff_type_e
-
- -

Type of one element of a difference list.

- - - -
Enumerator
HWLOC_TOPOLOGY_DIFF_OBJ_ATTR 

An object attribute was changed. The union is a hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s.

-
HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX 

The difference is too complex, it cannot be represented. The difference below this object has not been checked. hwloc_topology_diff_build() will return 1.

-

The union is a hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s.

-
- -
-
-

Function Documentation

- -

◆ hwloc_topology_diff_apply()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_topology_diff_apply (hwloc_topology_t topology,
hwloc_topology_diff_t diff,
unsigned long flags 
)
-
- -

Apply a topology diff to an existing topology.

-

flags is an OR'ed set of hwloc_topology_diff_apply_flags_e.

-

The new topology is modified in place. hwloc_topology_dup() may be used to duplicate it before patching.

-

If the difference cannot be applied entirely, all previous applied elements are unapplied before returning.

-
Returns
0 on success.
-
--N if applying the difference failed while trying to apply the N-th part of the difference. For instance -1 is returned if the very first difference element could not be applied.
- -
-
- -

◆ hwloc_topology_diff_build()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_topology_diff_build (hwloc_topology_t topology,
hwloc_topology_t newtopology,
unsigned long flags,
hwloc_topology_diff_t * diff 
)
-
- -

Compute the difference between 2 topologies.

-

The difference is stored as a list of hwloc_topology_diff_t entries starting at diff. It is computed by doing a depth-first traversal of both topology trees simultaneously.

-

If the difference between 2 objects is too complex to be represented (for instance if some objects have different types, or different numbers of children), a special diff entry of type HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX is queued. The computation of the diff does not continue below these objects. So each such diff entry means that the difference between two subtrees could not be computed.

-
Returns
0 if the difference can be represented properly.
-
-0 with diff pointing to NULL if there is no difference between the topologies.
-
-1 if the difference is too complex (see above). Some entries in the list will be of type HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX.
-
--1 on any other error.
-
Note
flags is currently not used. It should be 0.
-
-The output diff has to be freed with hwloc_topology_diff_destroy().
-
-The output diff can only be exported to XML or passed to hwloc_topology_diff_apply() if 0 was returned, i.e. if no entry of type HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX is listed.
-
-The output diff may be modified by removing some entries from the list. The removed entries should be freed by passing them to to hwloc_topology_diff_destroy() (possible as another list).
- -
-
- -

◆ hwloc_topology_diff_destroy()

- -
-
- - - - - - - - -
int hwloc_topology_diff_destroy (hwloc_topology_diff_t diff)
-
- -

Destroy a list of topology differences.

- -
-
- -

◆ hwloc_topology_diff_export_xml()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_topology_diff_export_xml (hwloc_topology_diff_t diff,
const char * refname,
const char * xmlpath 
)
-
- -

Export a list of topology differences to a XML file.

-

If not NULL, refname defines an identifier string for the reference topology which was used as a base when computing this difference. This identifier is usually the name of the other XML file that contains the reference topology. This attribute is given back when reading the diff from XML.

- -
-
- -

◆ hwloc_topology_diff_export_xmlbuffer()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_topology_diff_export_xmlbuffer (hwloc_topology_diff_t diff,
const char * refname,
char ** xmlbuffer,
int * buflen 
)
-
- -

Export a list of topology differences to a XML buffer.

-

If not NULL, refname defines an identifier string for the reference topology which was used as a base when computing this difference. This identifier is usually the name of the other XML file that contains the reference topology. This attribute is given back when reading the diff from XML.

-

The returned buffer ends with a \0 that is included in the returned length.

-
Note
The XML buffer should later be freed with hwloc_free_xmlbuffer().
- -
-
- -

◆ hwloc_topology_diff_load_xml()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_topology_diff_load_xml (const char * xmlpath,
hwloc_topology_diff_t * diff,
char ** refname 
)
-
- -

Load a list of topology differences from a XML file.

-

If not NULL, refname will be filled with the identifier string of the reference topology for the difference file, if any was specified in the XML file. This identifier is usually the name of the other XML file that contains the reference topology.

-
Note
the pointer returned in refname should later be freed by the caller.
- -
-
- -

◆ hwloc_topology_diff_load_xmlbuffer()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_topology_diff_load_xmlbuffer (const char * xmlbuffer,
int buflen,
hwloc_topology_diff_t * diff,
char ** refname 
)
-
- -

Load a list of topology differences from a XML buffer.

-

If not NULL, refname will be filled with the identifier string of the reference topology for the difference file, if any was specified in the XML file. This identifier is usually the name of the other XML file that contains the reference topology.

-
Note
the pointer returned in refname should later be freed by the caller.
- -
-
-
- - - - - - - -
-
-Functions
-
-
Sharing topologies between processes
-
-
- - - - - - - - -

-Functions

int hwloc_shmem_topology_get_length (hwloc_topology_t topology, size_t *lengthp, unsigned long flags)
 
int hwloc_shmem_topology_write (hwloc_topology_t topology, int fd, hwloc_uint64_t fileoffset, void *mmap_address, size_t length, unsigned long flags)
 
int hwloc_shmem_topology_adopt (hwloc_topology_t *topologyp, int fd, hwloc_uint64_t fileoffset, void *mmap_address, size_t length, unsigned long flags)
 
-

Detailed Description

-

These functions are used to share a topology between processes by duplicating it into a file-backed shared-memory buffer.

-

The master process must first get the required shared-memory size for storing this topology with hwloc_shmem_topology_get_length().

-

Then it must find a virtual memory area of that size that is available in all processes (identical virtual addresses in all processes). On Linux, this can be done by comparing holes found in /proc/<pid>/maps for each process.

-

Once found, it must open a destination file for storing the buffer, and pass it to hwloc_shmem_topology_write() together with virtual memory address and length obtained above.

-

Other processes may then adopt this shared topology by opening the same file and passing it to hwloc_shmem_topology_adopt() with the exact same virtual memory address and length.

-

Function Documentation

- -

◆ hwloc_shmem_topology_adopt()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_shmem_topology_adopt (hwloc_topology_t * topologyp,
int fd,
hwloc_uint64_t fileoffset,
void * mmap_address,
size_t length,
unsigned long flags 
)
-
- -

Adopt a shared memory topology stored in a file.

-

Map a file in virtual memory and adopt the topology that was previously stored there with hwloc_shmem_topology_write().

-

The returned adopted topology in topologyp can be used just like any topology. And it must be destroyed with hwloc_topology_destroy() as usual.

-

However the topology is read-only. For instance, it cannot be modified with hwloc_topology_restrict() and object userdata pointers cannot be changed.

-

The segment of the file pointed by descriptor fd, starting at offset fileoffset, and of length length (in bytes), will be mapped at virtual address mmap_address.

-

The file pointed by descriptor fd, the offset fileoffset, the requested mapping virtual address mmap_address and the length length must be identical to what was given to hwloc_shmem_topology_write() earlier.

-
Note
Flags flags are currently unused, must be 0.
-
-The object userdata pointer should not be used unless the process that created the shared topology also placed userdata-pointed buffers in shared memory.
-
-This function takes care of calling hwloc_topology_abi_check().
-
Returns
-1 with errno set to EBUSY if the virtual memory mapping defined by mmap_address and length isn't available in the process.
-
--1 with errno set to EINVAL if fileoffset, mmap_address or length aren't page-aligned, or do not match what was given to hwloc_shmem_topology_write() earlier.
-
--1 with errno set to EINVAL if the layout of the topology structure is different between the writer process and the adopter process.
- -
-
- -

◆ hwloc_shmem_topology_get_length()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_shmem_topology_get_length (hwloc_topology_t topology,
size_t * lengthp,
unsigned long flags 
)
-
- -

Get the required shared memory length for storing a topology.

-

This length (in bytes) must be used in hwloc_shmem_topology_write() and hwloc_shmem_topology_adopt() later.

-
Note
Flags flags are currently unused, must be 0.
- -
-
- -

◆ hwloc_shmem_topology_write()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_shmem_topology_write (hwloc_topology_t topology,
int fd,
hwloc_uint64_t fileoffset,
void * mmap_address,
size_t length,
unsigned long flags 
)
-
- -

Duplicate a topology to a shared memory file.

-

Temporarily map a file in virtual memory and duplicate the topology topology by allocating duplicates in there.

-

The segment of the file pointed by descriptor fd, starting at offset fileoffset, and of length length (in bytes), will be temporarily mapped at virtual address mmap_address during the duplication.

-

The mapping length length must have been previously obtained with hwloc_shmem_topology_get_length() and the topology must not have been modified in the meantime.

-
Note
Flags flags are currently unused, must be 0.
-
-The object userdata pointer is duplicated but the pointed buffer is not. However the caller may also allocate it manually in shared memory to share it as well.
-
Returns
-1 with errno set to EBUSY if the virtual memory mapping defined by mmap_address and length isn't available in the process.
-
--1 with errno set to EINVAL if fileoffset, mmap_address or length aren't page-aligned.
- -
-
-
- - - - - - - -
-
-Data Structures
-
-
Components and Plugins: Discovery components
-
-
- - - - -

-Data Structures

struct  hwloc_disc_component
 
-

Detailed Description

-
Note
These structures and functions may change when HWLOC_COMPONENT_ABI is modified.
-
- - - - - - - -
-
-Data Structures | -Typedefs | -Enumerations | -Functions
-
-
Components and Plugins: Discovery backends
-
-
- - - - - - -

-Data Structures

struct  hwloc_disc_status
 
struct  hwloc_backend
 
- - - -

-Typedefs

typedef enum hwloc_disc_phase_e hwloc_disc_phase_t
 
- - - - - -

-Enumerations

enum  hwloc_disc_phase_e {
-  HWLOC_DISC_PHASE_GLOBAL -, HWLOC_DISC_PHASE_CPU -, HWLOC_DISC_PHASE_MEMORY -, HWLOC_DISC_PHASE_PCI -,
-  HWLOC_DISC_PHASE_IO -, HWLOC_DISC_PHASE_MISC -, HWLOC_DISC_PHASE_ANNOTATE -, HWLOC_DISC_PHASE_TWEAK -
- }
 
enum  hwloc_disc_status_flag_e { HWLOC_DISC_STATUS_FLAG_GOT_ALLOWED_RESOURCES - }
 
- - - - - -

-Functions

struct hwloc_backend * hwloc_backend_alloc (struct hwloc_topology *topology, struct hwloc_disc_component *component)
 
int hwloc_backend_enable (struct hwloc_backend *backend)
 
-

Detailed Description

-
Note
These structures and functions may change when HWLOC_COMPONENT_ABI is modified.
-

Typedef Documentation

- -

◆ hwloc_disc_phase_t

- -
-
- - - - -
typedef enum hwloc_disc_phase_e hwloc_disc_phase_t
-
- -

Discovery phase.

- -
-
-

Enumeration Type Documentation

- -

◆ hwloc_disc_phase_e

- -
-
- - - - -
enum hwloc_disc_phase_e
-
- -

Discovery phase.

- - - - - - - - - -
Enumerator
HWLOC_DISC_PHASE_GLOBAL 

xml or synthetic, platform-specific components such as bgq. Discovers everything including CPU, memory, I/O and everything else. A component with a Global phase usually excludes all other phases.

-
HWLOC_DISC_PHASE_CPU 

CPU discovery.

-
HWLOC_DISC_PHASE_MEMORY 

Attach memory to existing CPU objects.

-
HWLOC_DISC_PHASE_PCI 

Attach PCI devices and bridges to existing CPU objects.

-
HWLOC_DISC_PHASE_IO 

I/O discovery that requires PCI devices (OS devices such as OpenCL, CUDA, etc.).

-
HWLOC_DISC_PHASE_MISC 

Misc objects that gets added below anything else.

-
HWLOC_DISC_PHASE_ANNOTATE 

Annotating existing objects, adding distances, etc.

-
HWLOC_DISC_PHASE_TWEAK 

Final tweaks to a ready-to-use topology. This phase runs once the topology is loaded, before it is returned to the topology. Hence it may only use the main hwloc API for modifying the topology, for instance by restricting it, adding info attributes, etc.

-
- -
-
- -

◆ hwloc_disc_status_flag_e

- -
-
- - - - -
enum hwloc_disc_status_flag_e
-
- -

Discovery status flags.

- - -
Enumerator
HWLOC_DISC_STATUS_FLAG_GOT_ALLOWED_RESOURCES 

The sets of allowed resources were already retrieved.

-
- -
-
-

Function Documentation

- -

◆ hwloc_backend_alloc()

- -
-
- - - - - - - - - - - - - - - - - - -
struct hwloc_backend* hwloc_backend_alloc (struct hwloc_topology * topology,
struct hwloc_disc_component * component 
)
-
- -

Allocate a backend structure, set good default values, initialize backend->component and topology, etc. The caller will then modify whatever needed, and call hwloc_backend_enable().

- -
-
- -

◆ hwloc_backend_enable()

- -
-
- - - - - - - - -
int hwloc_backend_enable (struct hwloc_backend * backend)
-
- -

Enable a previously allocated and setup backend.

- -
-
-
- - - - - - - -
-
-Data Structures | -Typedefs | -Enumerations
-
-
Components and Plugins: Generic components
-
-
- - - - -

-Data Structures

struct  hwloc_component
 
- - - -

-Typedefs

typedef enum hwloc_component_type_e hwloc_component_type_t
 
- - - -

-Enumerations

enum  hwloc_component_type_e { HWLOC_COMPONENT_TYPE_DISC -, HWLOC_COMPONENT_TYPE_XML - }
 
-

Detailed Description

-
Note
These structures and functions may change when HWLOC_COMPONENT_ABI is modified.
-

Typedef Documentation

- -

◆ hwloc_component_type_t

- -
-
- - - - -
typedef enum hwloc_component_type_e hwloc_component_type_t
-
- -

Generic component type.

- -
-
-

Enumeration Type Documentation

- -

◆ hwloc_component_type_e

- -
-
- - - - -
enum hwloc_component_type_e
-
- -

Generic component type.

- - - -
Enumerator
HWLOC_COMPONENT_TYPE_DISC 

The data field must point to a struct hwloc_disc_component.

-
HWLOC_COMPONENT_TYPE_XML 

The data field must point to a struct hwloc_xml_component.

-
- -
-
-
- - - - - - - -
-
-Macros | -Functions
-
-
Components and Plugins: Core functions to be used by components
-
-
- - - - - - -

-Macros

#define HWLOC_SHOW_CRITICAL_ERRORS()   (hwloc_hide_errors() < 2)
 
#define HWLOC_SHOW_ALL_ERRORS()   (hwloc_hide_errors() == 0)
 
- - - - - - - - - - - - - - - -

-Functions

int hwloc_hide_errors (void)
 
hwloc_obj_t hwloc__insert_object_by_cpuset (struct hwloc_topology *topology, hwloc_obj_t root, hwloc_obj_t obj, const char *reason)
 
void hwloc_insert_object_by_parent (struct hwloc_topology *topology, hwloc_obj_t parent, hwloc_obj_t obj)
 
hwloc_obj_t hwloc_alloc_setup_object (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned os_index)
 
int hwloc_obj_add_children_sets (hwloc_obj_t obj)
 
int hwloc_topology_reconnect (hwloc_topology_t topology, unsigned long flags)
 
static int hwloc_plugin_check_namespace (const char *pluginname, const char *symbol)
 
-

Detailed Description

-
Note
These structures and functions may change when HWLOC_COMPONENT_ABI is modified.
-

Macro Definition Documentation

- -

◆ HWLOC_SHOW_ALL_ERRORS

- -
-
- - - - - - - -
#define HWLOC_SHOW_ALL_ERRORS()   (hwloc_hide_errors() == 0)
-
- -
-
- -

◆ HWLOC_SHOW_CRITICAL_ERRORS

- -
-
- - - - - - - -
#define HWLOC_SHOW_CRITICAL_ERRORS()   (hwloc_hide_errors() < 2)
-
- -
-
-

Function Documentation

- -

◆ hwloc__insert_object_by_cpuset()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
hwloc_obj_t hwloc__insert_object_by_cpuset (struct hwloc_topology * topology,
hwloc_obj_t root,
hwloc_obj_t obj,
const char * reason 
)
-
- -

Add an object to the topology.

-

Insert new object obj in the topology starting under existing object root (if NULL, the topology root object is used).

-

It is sorted along the tree of other objects according to the inclusion of cpusets, to eventually be added as a child of the smallest object including this object.

-

If the cpuset is empty, the type of the object (and maybe some attributes) must be enough to find where to insert the object. This is especially true for NUMA nodes with memory and no CPUs.

-

The given object should not have children.

-

This shall only be called before levels are built.

-

The caller should check whether the object type is filtered-out before calling this function.

-

The topology cpuset/nodesets will be enlarged to include the object sets.

-

reason is a unique string identifying where and why this insertion call was performed (it will be displayed in case of internal insertion error).

-

Returns the object on success. Returns NULL and frees obj on error. Returns another object and frees obj if it was merged with an identical pre-existing object.

- -
-
- -

◆ hwloc_alloc_setup_object()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
hwloc_obj_t hwloc_alloc_setup_object (hwloc_topology_t topology,
hwloc_obj_type_t type,
unsigned os_index 
)
-
- -

Allocate and initialize an object of the given type and physical index.

-

If os_index is unknown or irrelevant, use HWLOC_UNKNOWN_INDEX.

- -
-
- -

◆ hwloc_hide_errors()

- -
-
- - - - - - - - -
int hwloc_hide_errors (void )
-
- -

Check whether error messages are hidden.

-

Callers should print critical error messages (e.g. invalid hw topo info, invalid config) only if this function returns strictly less than 2.

-

Callers should print non-critical error messages (e.g. failure to initialize CUDA) if this function returns 0.

-

This function return 1 by default (show critical only), 0 in lstopo (show all), or anything set in HWLOC_HIDE_ERRORS in the environment.

-

Use macros HWLOC_SHOW_CRITICAL_ERRORS() and HWLOC_SHOW_ALL_ERRORS() for clarity.

- -
-
- -

◆ hwloc_insert_object_by_parent()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
void hwloc_insert_object_by_parent (struct hwloc_topology * topology,
hwloc_obj_t parent,
hwloc_obj_t obj 
)
-
- -

Insert an object somewhere in the topology.

-

It is added as the last child of the given parent. The cpuset is completely ignored, so strange objects such as I/O devices should preferably be inserted with this.

-

When used for "normal" children with cpusets (when importing from XML when duplicating a topology), the caller should make sure that:

    -
  • children are inserted in order,
    • -
  • children cpusets do not intersect.
    • -
-

The given object may have normal, I/O or Misc children, as long as they are in order as well. These children must have valid parent and next_sibling pointers.

-

The caller should check whether the object type is filtered-out before calling this function.

- -
-
- -

◆ hwloc_obj_add_children_sets()

- -
-
- - - - - - - - -
int hwloc_obj_add_children_sets (hwloc_obj_t obj)
-
- -

Setup object cpusets/nodesets by OR'ing its children.

-

Used when adding an object late in the topology. Will update the new object by OR'ing all its new children sets.

-

Used when PCI backend adds a hostbridge parent, when distances add a new Group, etc.

- -
-
- -

◆ hwloc_plugin_check_namespace()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static int hwloc_plugin_check_namespace (const char * pluginname,
const char * symbol 
)
- 		-inlinestatic
-
- -

Make sure that plugins can lookup core symbols.

-

This is a sanity check to avoid lazy-lookup failures when libhwloc is loaded within a plugin, and later tries to load its own plugins. This may fail (and abort the program) if libhwloc symbols are in a private namespace.

-
Returns
0 on success.
-
--1 if the plugin cannot be successfully loaded. The caller plugin init() callback should return a negative error code as well.
-

Plugins should call this function in their init() callback to avoid later crashes if lazy symbol resolution is used by the upper layer that loaded hwloc (e.g. OpenCL implementations using dlopen with RTLD_LAZY).

-
Note
The build system must define HWLOC_INSIDE_PLUGIN if and only if building the caller as a plugin.
-
-This function should remain inline so plugins can call it even when they cannot find libhwloc symbols.
- -
-
- -

◆ hwloc_topology_reconnect()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_topology_reconnect (hwloc_topology_t topology,
unsigned long flags 
)
-
- -

Request a reconnection of children and levels in the topology.

-

May be used by backends during discovery if they need arrays or lists of object within levels or children to be fully connected.

-

flags is currently unused, must 0.

- -
-
-
- - - - - - - -
-
-Functions
-
-
Components and Plugins: Filtering objects
-
-
- - - - - - - - - - -

-Functions

static int hwloc_filter_check_pcidev_subtype_important (unsigned classid)
 
static int hwloc_filter_check_osdev_subtype_important (hwloc_obj_osdev_type_t subtype)
 
static int hwloc_filter_check_keep_object_type (hwloc_topology_t topology, hwloc_obj_type_t type)
 
static int hwloc_filter_check_keep_object (hwloc_topology_t topology, hwloc_obj_t obj)
 
-

Detailed Description

-
Note
These structures and functions may change when HWLOC_COMPONENT_ABI is modified.
-

Function Documentation

- -

◆ hwloc_filter_check_keep_object()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static int hwloc_filter_check_keep_object (hwloc_topology_t topology,
hwloc_obj_t obj 
)
- 		-inlinestatic
-
- -

Check whether the given object should be filtered-out.

-
Returns
1 if the object type should be kept, 0 otherwise.
- -
-
- -

◆ hwloc_filter_check_keep_object_type()

- -
-
- - - - - -
- - - - - - - - - - - - - - - - - - -
static int hwloc_filter_check_keep_object_type (hwloc_topology_t topology,
hwloc_obj_type_t type 
)
- 		-inlinestatic
-
- -

Check whether a non-I/O object type should be filtered-out.

-

Cannot be used for I/O objects.

-
Returns
1 if the object type should be kept, 0 otherwise.
- -
-
- -

◆ hwloc_filter_check_osdev_subtype_important()

- -
-
- - - - - -
- - - - - - - - -
static int hwloc_filter_check_osdev_subtype_important (hwloc_obj_osdev_type_t subtype)
- 		-inlinestatic
-
- -

Check whether the given OS device subtype is important.

-
Returns
1 if important, 0 otherwise.
- -
-
- -

◆ hwloc_filter_check_pcidev_subtype_important()

- -
-
- - - - - -
- - - - - - - - -
static int hwloc_filter_check_pcidev_subtype_important (unsigned classid)
- 		-inlinestatic
-
- -

Check whether the given PCI device classid is important.

-
Returns
1 if important, 0 otherwise.
- -
-
-
- - - - - - - -
-
-Functions
-
-
Components and Plugins: helpers for PCI discovery
-
-
- - - - - - - - - - - - - - -

-Functions

unsigned hwloc_pcidisc_find_cap (const unsigned char *config, unsigned cap)
 
int hwloc_pcidisc_find_linkspeed (const unsigned char *config, unsigned offset, float *linkspeed)
 
hwloc_obj_type_t hwloc_pcidisc_check_bridge_type (unsigned device_class, const unsigned char *config)
 
int hwloc_pcidisc_find_bridge_buses (unsigned domain, unsigned bus, unsigned dev, unsigned func, unsigned *secondary_busp, unsigned *subordinate_busp, const unsigned char *config)
 
void hwloc_pcidisc_tree_insert_by_busid (struct hwloc_obj **treep, struct hwloc_obj *obj)
 
int hwloc_pcidisc_tree_attach (struct hwloc_topology *topology, struct hwloc_obj *tree)
 
-

Detailed Description

-
Note
These structures and functions may change when HWLOC_COMPONENT_ABI is modified.
-

Function Documentation

- -

◆ hwloc_pcidisc_check_bridge_type()

- -
-
- - - - - - - - - - - - - - - - - - -
hwloc_obj_type_t hwloc_pcidisc_check_bridge_type (unsigned device_class,
const unsigned char * config 
)
-
- -

Return the hwloc object type (PCI device or Bridge) for the given class and configuration space.

-

This function requires 16 bytes of common configuration header at the beginning of config.

- -
-
- -

◆ hwloc_pcidisc_find_bridge_buses()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_pcidisc_find_bridge_buses (unsigned domain,
unsigned bus,
unsigned dev,
unsigned func,
unsigned * secondary_busp,
unsigned * subordinate_busp,
const unsigned char * config 
)
-
- -

Fills the attributes of the given PCI bridge using the given PCI config space.

-

This function requires 32 bytes of common configuration header at the beginning of config.

-

Returns -1 and destroys /p obj if bridge fields are invalid.

- -
-
- -

◆ hwloc_pcidisc_find_cap()

- -
-
- - - - - - - - - - - - - - - - - - -
unsigned hwloc_pcidisc_find_cap (const unsigned char * config,
unsigned cap 
)
-
- -

Return the offset of the given capability in the PCI config space buffer.

-

This function requires a 256-bytes config space. Unknown/unavailable bytes should be set to 0xff.

- -
-
- -

◆ hwloc_pcidisc_find_linkspeed()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_pcidisc_find_linkspeed (const unsigned char * config,
unsigned offset,
float * linkspeed 
)
-
- -

Fill linkspeed by reading the PCI config space where PCI_CAP_ID_EXP is at position offset.

-

Needs 20 bytes of EXP capability block starting at offset in the config space for registers up to link status.

- -
-
- -

◆ hwloc_pcidisc_tree_attach()

- -
-
- - - - - - - - - - - - - - - - - - -
int hwloc_pcidisc_tree_attach (struct hwloc_topology * topology,
struct hwloc_obj * tree 
)
-
- -

Add some hostbridges on top of the given tree of PCI objects and attach them to the topology.

-

Other backends may lookup PCI objects or localities (for instance to attach OS devices) by using hwloc_pcidisc_find_by_busid() or hwloc_pcidisc_find_busid_parent().

- -
-
- -

◆ hwloc_pcidisc_tree_insert_by_busid()

- -
-
- - - - - - - - - - - - - - - - - - -
void hwloc_pcidisc_tree_insert_by_busid (struct hwloc_obj ** treep,
struct hwloc_obj * obj 
)
-
- -

Insert a PCI object in the given PCI tree by looking at PCI bus IDs.

-

If treep points to NULL, the new object is inserted there.

- -
-
-
- - - - - - - -
-
-Typedefs | -Functions
-
-
Components and Plugins: finding PCI objects during other discoveries
-
-
- - - - -

-Typedefs

typedef void * hwloc_backend_distances_add_handle_t
 
- - - - - - - - - - - -

-Functions

struct hwloc_obj * hwloc_pci_find_parent_by_busid (struct hwloc_topology *topology, unsigned domain, unsigned bus, unsigned dev, unsigned func)
 
struct hwloc_obj * hwloc_pci_find_by_busid (struct hwloc_topology *topology, unsigned domain, unsigned bus, unsigned dev, unsigned func)
 
hwloc_backend_distances_add_handle_t hwloc_backend_distances_add_create (hwloc_topology_t topology, const char *name, unsigned long kind, unsigned long flags)
 
int hwloc_backend_distances_add_values (hwloc_topology_t topology, hwloc_backend_distances_add_handle_t handle, unsigned nbobjs, hwloc_obj_t *objs, hwloc_uint64_t *values, unsigned long flags)
 
int hwloc_backend_distances_add_commit (hwloc_topology_t topology, hwloc_backend_distances_add_handle_t handle, unsigned long flags)
 
-

Detailed Description

-
Note
These structures and functions may change when HWLOC_COMPONENT_ABI is modified.
-

Typedef Documentation

- -

◆ hwloc_backend_distances_add_handle_t

- -
-
- - - - -
typedef void* hwloc_backend_distances_add_handle_t
-
- -

Handle to a new distances structure during its addition to the topology.

- -
-
-

Function Documentation

- -

◆ hwloc_backend_distances_add_commit()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_backend_distances_add_commit (hwloc_topology_t topology,
hwloc_backend_distances_add_handle_t handle,
unsigned long flags 
)
-
- -

Commit a new distances structure.

-

This is similar to hwloc_distances_add_commit() but this variant is designed for backend inserting distances during topology discovery.

- -
-
- -

◆ hwloc_backend_distances_add_create()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
hwloc_backend_distances_add_handle_t hwloc_backend_distances_add_create (hwloc_topology_t topology,
const char * name,
unsigned long kind,
unsigned long flags 
)
-
- -

Create a new empty distances structure.

-

This is identical to hwloc_distances_add_create() but this variant is designed for backend inserting distances during topology discovery.

- -
-
- -

◆ hwloc_backend_distances_add_values()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int hwloc_backend_distances_add_values (hwloc_topology_t topology,
hwloc_backend_distances_add_handle_t handle,
unsigned nbobjs,
hwloc_obj_t * objs,
hwloc_uint64_t * values,
unsigned long flags 
)
-
- -

Specify the objects and values in a new empty distances structure.

-

This is similar to hwloc_distances_add_values() but this variant is designed for backend inserting distances during topology discovery.

-

The only semantical difference is that objs and values are not duplicated, but directly attached to the topology. On success, these arrays are given to the core and should not ever be freed by the caller anymore.

- -
-
- -

◆ hwloc_pci_find_by_busid()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
struct hwloc_obj* hwloc_pci_find_by_busid (struct hwloc_topology * topology,
unsigned domain,
unsigned bus,
unsigned dev,
unsigned func 
)
-
- -

Find the PCI device or bridge matching a PCI bus ID exactly.

-

This is useful for adding specific information about some objects based on their PCI id. When it comes to attaching objects based on PCI locality, hwloc_pci_find_parent_by_busid() should be preferred.

- -
-
- -

◆ hwloc_pci_find_parent_by_busid()

- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
struct hwloc_obj* hwloc_pci_find_parent_by_busid (struct hwloc_topology * topology,
unsigned domain,
unsigned bus,
unsigned dev,
unsigned func 
)
-
- -

Find the object or a parent of a PCI bus ID.

-

When attaching a new object (typically an OS device) whose locality is specified by PCI bus ID, this function returns the PCI object to use as a parent for attaching.

-

If the exact PCI device with this bus ID exists, it is returned. Otherwise (for instance if it was filtered out), the function returns another object with similar locality (for instance a parent bridge, or the local CPU Package).

- -
-
-
- - - - - - - -
-
-Enumerations
-
-
Netloc API
-
-
- - - - -

-Enumerations

enum  {
-  NETLOC_SUCCESS = 0 -, NETLOC_ERROR = -1 -, NETLOC_ERROR_NOTDIR = -2 -, NETLOC_ERROR_NOENT = -3 -,
-  NETLOC_ERROR_EMPTY = -4 -, NETLOC_ERROR_MULTIPLE = -5 -, NETLOC_ERROR_NOT_IMPL = -6 -, NETLOC_ERROR_EXISTS = -7 -,
-  NETLOC_ERROR_NOT_FOUND = -8 -, NETLOC_ERROR_MAX = -9 -
- }
 
-

Detailed Description

-

Enumeration Type Documentation

- -

◆ anonymous enum

- -
-
- - - - -
anonymous enum
-
-

Return codes

- - - - - - - - - - - -
Enumerator
NETLOC_SUCCESS 

Success

-
NETLOC_ERROR 

Error: General condition

-
NETLOC_ERROR_NOTDIR 

Error: URI is not a directory

-
NETLOC_ERROR_NOENT 

Error: URI is invalid, no such entry

-
NETLOC_ERROR_EMPTY 

Error: No networks found

-
NETLOC_ERROR_MULTIPLE 

Error: Multiple matching networks found

-
NETLOC_ERROR_NOT_IMPL 

Error: Interface not implemented

-
NETLOC_ERROR_EXISTS 

Error: If the entry already exists when trying to add to a lookup table

-
NETLOC_ERROR_NOT_FOUND 

Error: No path found

-
NETLOC_ERROR_MAX 

Error: Enum upper bound marker. No errors less than this number Will not be returned externally.

-
- -
-
-
- - - - - - - -
-
-Data Fields
-
-
hwloc_obj Struct Reference
Object Structure and Attributes
-
-
- -

#include <hwloc.h>

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

-Data Fields

hwloc_obj_type_t type
 
char * subtype
 
unsigned os_index
 
char * name
 
hwloc_uint64_t total_memory
 
union hwloc_obj_attr_u * attr
 
int depth
 
unsigned logical_index
 
struct hwloc_obj * next_cousin
 
struct hwloc_obj * prev_cousin
 
struct hwloc_obj * parent
 
unsigned sibling_rank
 
struct hwloc_obj * next_sibling
 
struct hwloc_obj * prev_sibling
 
int symmetric_subtree
 
hwloc_cpuset_t cpuset
 
hwloc_cpuset_t complete_cpuset
 
hwloc_nodeset_t nodeset
 
hwloc_nodeset_t complete_nodeset
 
struct hwloc_info_s * infos
 
unsigned infos_count
 
void * userdata
 
hwloc_uint64_t gp_index
 
List and array of normal children below this object (except Memory, I/O and Misc children).
unsigned arity
 
struct hwloc_obj ** children
 
struct hwloc_obj * first_child
 
struct hwloc_obj * last_child
 
List of Memory children below this object.
unsigned memory_arity
 
struct hwloc_obj * memory_first_child
 
List of I/O children below this object.
unsigned io_arity
 
struct hwloc_obj * io_first_child
 
List of Misc children below this object.
unsigned misc_arity
 
struct hwloc_obj * misc_first_child
 
-

Detailed Description

-

Structure of a topology object.

-

Applications must not modify any field except hwloc_obj.userdata.

-

Field Documentation

- -

◆ arity

- -
-
- - - - -
unsigned hwloc_obj::arity
-
- -

Number of normal children. Memory, Misc and I/O children are not listed here but rather in their dedicated children list.

- -
-
- -

◆ attr

- -
-
- - - - -
union hwloc_obj_attr_u* hwloc_obj::attr
-
- -

Object type-specific Attributes, may be NULL if no attribute value was found.

- -
-
- -

◆ children

- -
-
- - - - -
struct hwloc_obj** hwloc_obj::children
-
- -

Normal children, children[0 .. arity -1].

- -
-
- -

◆ complete_cpuset

- -
-
- - - - -
hwloc_cpuset_t hwloc_obj::complete_cpuset
-
- -

The complete CPU set of processors of this object,.

-

This may include not only the same as the cpuset field, but also some CPUs for which topology information is unknown or incomplete, some offlines CPUs, and the CPUs that are ignored when the HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED flag is not set. Thus no corresponding PU object may be found in the topology, because the precise position is undefined. It is however known that it would be somewhere under this object.

-
Note
Its value must not be changed, hwloc_bitmap_dup() must be used instead.
- -
-
- -

◆ complete_nodeset

- -
-
- - - - -
hwloc_nodeset_t hwloc_obj::complete_nodeset
-
- -

The complete NUMA node set of this object,.

-

This may include not only the same as the nodeset field, but also some NUMA nodes for which topology information is unknown or incomplete, some offlines nodes, and the nodes that are ignored when the HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED flag is not set. Thus no corresponding NUMA node object may be found in the topology, because the precise position is undefined. It is however known that it would be somewhere under this object.

-

If there are no NUMA nodes in the machine, all the memory is close to this object, so only the first bit is set in complete_nodeset.

-
Note
Its value must not be changed, hwloc_bitmap_dup() must be used instead.
- -
-
- -

◆ cpuset

- -
-
- - - - -
hwloc_cpuset_t hwloc_obj::cpuset
-
- -

CPUs covered by this object.

-

This is the set of CPUs for which there are PU objects in the topology under this object, i.e. which are known to be physically contained in this object and known how (the children path between this object and the PU objects).

-

If the HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED configuration flag is set, some of these CPUs may be online but not allowed for binding, see hwloc_topology_get_allowed_cpuset().

-
Note
All objects have non-NULL CPU and node sets except Misc and I/O objects.
-
-Its value must not be changed, hwloc_bitmap_dup() must be used instead.
- -
-
- -

◆ depth

- -
-
- - - - -
int hwloc_obj::depth
-
- -

Vertical index in the hierarchy.

-

For normal objects, this is the depth of the horizontal level that contains this object and its cousins of the same type. If the topology is symmetric, this is equal to the parent depth plus one, and also equal to the number of parent/child links from the root object to here.

-

For special objects (NUMA nodes, I/O and Misc) that are not in the main tree, this is a special negative value that corresponds to their dedicated level, see hwloc_get_type_depth() and hwloc_get_type_depth_e. Those special values can be passed to hwloc functions such hwloc_get_nbobjs_by_depth() as usual.

- -
-
- -

◆ first_child

- -
-
- - - - -
struct hwloc_obj* hwloc_obj::first_child
-
- -

First normal child.

- -
-
- -

◆ gp_index

- -
-
- - - - -
hwloc_uint64_t hwloc_obj::gp_index
-
- -

Global persistent index. Generated by hwloc, unique across the topology (contrary to os_index) and persistent across topology changes (contrary to logical_index). Mostly used internally, but could also be used by application to identify objects.

- -
-
- -

◆ infos

- -
-
- - - - -
struct hwloc_info_s* hwloc_obj::infos
-
- -

Array of stringified info type=name.

- -
-
- -

◆ infos_count

- -
-
- - - - -
unsigned hwloc_obj::infos_count
-
- -

Size of infos array.

- -
-
- -

◆ io_arity

- -
-
- - - - -
unsigned hwloc_obj::io_arity
-
- -

Number of I/O children. These children are listed in io_first_child.

- -
-
- -

◆ io_first_child

- -
-
- - - - -
struct hwloc_obj* hwloc_obj::io_first_child
-
- -

First I/O child. Bridges, PCI and OS devices are listed here (io_arity and io_first_child) instead of in the normal children list. See also hwloc_obj_type_is_io().

- -
-
- -

◆ last_child

- -
-
- - - - -
struct hwloc_obj* hwloc_obj::last_child
-
- -

Last normal child.

- -
-
- -

◆ logical_index

- -
-
- - - - -
unsigned hwloc_obj::logical_index
-
- -

Horizontal index in the whole list of similar objects, hence guaranteed unique across the entire machine. Could be a "cousin_rank" since it's the rank within the "cousin" list below Note that this index may change when restricting the topology or when inserting a group.

- -
-
- -

◆ memory_arity

- -
-
- - - - -
unsigned hwloc_obj::memory_arity
-
- -

Number of Memory children. These children are listed in memory_first_child.

- -
-
- -

◆ memory_first_child

- -
-
- - - - -
struct hwloc_obj* hwloc_obj::memory_first_child
-
- -

First Memory child. NUMA nodes and Memory-side caches are listed here (memory_arity and memory_first_child) instead of in the normal children list. See also hwloc_obj_type_is_memory().

-

A memory hierarchy starts from a normal CPU-side object (e.g. Package) and ends with NUMA nodes as leaves. There might exist some memory-side caches between them in the middle of the memory subtree.

- -
-
- -

◆ misc_arity

- -
-
- - - - -
unsigned hwloc_obj::misc_arity
-
- -

Number of Misc children. These children are listed in misc_first_child.

- -
-
- -

◆ misc_first_child

- -
-
- - - - -
struct hwloc_obj* hwloc_obj::misc_first_child
-
- -

First Misc child. Misc objects are listed here (misc_arity and misc_first_child) instead of in the normal children list.

- -
-
- -

◆ name

- -
-
- - - - -
char* hwloc_obj::name
-
- -

Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name string is more useful than numerical indexes.

- -
-
- -

◆ next_cousin

- -
-
- - - - -
struct hwloc_obj* hwloc_obj::next_cousin
-
- -

Next object of same type and depth.

- -
-
- -

◆ next_sibling

- -
-
- - - - -
struct hwloc_obj* hwloc_obj::next_sibling
-
- -

Next object below the same parent (inside the same list of children).

- -
-
- -

◆ nodeset

- -
-
- - - - -
hwloc_nodeset_t hwloc_obj::nodeset
-
- -

NUMA nodes covered by this object or containing this object.

-

This is the set of NUMA nodes for which there are NUMA node objects in the topology under or above this object, i.e. which are known to be physically contained in this object or containing it and known how (the children path between this object and the NUMA node objects).

-

In the end, these nodes are those that are close to the current object. Function hwloc_get_local_numanode_objs() may be used to list those NUMA nodes more precisely.

-

If the HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED configuration flag is set, some of these nodes may be online but not allowed for allocation, see hwloc_topology_get_allowed_nodeset().

-

If there are no NUMA nodes in the machine, all the memory is close to this object, so only the first bit may be set in nodeset.

-
Note
All objects have non-NULL CPU and node sets except Misc and I/O objects.
-
-Its value must not be changed, hwloc_bitmap_dup() must be used instead.
- -
-
- -

◆ os_index

- -
-
- - - - -
unsigned hwloc_obj::os_index
-
- -

OS-provided physical index number. It is not guaranteed unique across the entire machine, except for PUs and NUMA nodes. Set to HWLOC_UNKNOWN_INDEX if unknown or irrelevant for this object.

- -
-
- -

◆ parent

- -
-
- - - - -
struct hwloc_obj* hwloc_obj::parent
-
- -

Parent, NULL if root (Machine object)

- -
-
- -

◆ prev_cousin

- -
-
- - - - -
struct hwloc_obj* hwloc_obj::prev_cousin
-
- -

Previous object of same type and depth.

- -
-
- -

◆ prev_sibling

- -
-
- - - - -
struct hwloc_obj* hwloc_obj::prev_sibling
-
- -

Previous object below the same parent (inside the same list of children).

- -
-
- -

◆ sibling_rank

- -
-
- - - - -
unsigned hwloc_obj::sibling_rank
-
- -

Index in parent's children[] array. Or the index in parent's Memory, I/O or Misc children list.

- -
-
- -

◆ subtype

- -
-
- - - - -
char* hwloc_obj::subtype
-
- -

Subtype string to better describe the type field.

- -
-
- -

◆ symmetric_subtree

- -
-
- - - - -
int hwloc_obj::symmetric_subtree
-
- -

Set if the subtree of normal objects below this object is symmetric, which means all normal children and their children have identical subtrees.

-

Memory, I/O and Misc children are ignored.

-

If set in the topology root object, lstopo may export the topology as a synthetic string.

- -
-
- -

◆ total_memory

- -
-
- - - - -
hwloc_uint64_t hwloc_obj::total_memory
-
- -

Total memory (in bytes) in NUMA nodes below this object.

- -
-
- -

◆ type

- -
-
- - - - -
hwloc_obj_type_t hwloc_obj::type
-
- -

Type of object.

- -
-
- -

◆ userdata

- -
-
- - - - -
void* hwloc_obj::userdata
-
- -

Application-given private data pointer, initialized to NULL, use it as you wish. See hwloc_topology_set_userdata_export_callback() in hwloc/export.h if you wish to export this field to XML.

- -
-
-
The documentation for this struct was generated from the following file: -
- - - - - - - -
-
-Data Structures | -Data Fields
-
-
hwloc_obj_attr_u Union Reference
Object Structure and Attributes
-
-
- -

#include <hwloc.h>

- - - - - - - - - - - - - - -

-Data Structures

struct  hwloc_bridge_attr_s
 
struct  hwloc_cache_attr_s
 
struct  hwloc_group_attr_s
 
struct  hwloc_numanode_attr_s
 
struct  hwloc_osdev_attr_s
 
struct  hwloc_pcidev_attr_s
 
- - - - - - - - - - - - - -

-Data Fields

struct hwloc_obj_attr_u::hwloc_numanode_attr_s numanode
 
struct hwloc_obj_attr_u::hwloc_cache_attr_s cache
 
struct hwloc_obj_attr_u::hwloc_group_attr_s group
 
struct hwloc_obj_attr_u::hwloc_pcidev_attr_s pcidev
 
struct hwloc_obj_attr_u::hwloc_bridge_attr_s bridge
 
struct hwloc_obj_attr_u::hwloc_osdev_attr_s osdev
 
-

Detailed Description

-

Object type-specific Attributes.

-

Field Documentation

- -

◆ bridge

- -
-
- - - - -
struct hwloc_obj_attr_u::hwloc_bridge_attr_s hwloc_obj_attr_u::bridge
-
- -
-
- -

◆ cache

- -
-
- - - - -
struct hwloc_obj_attr_u::hwloc_cache_attr_s hwloc_obj_attr_u::cache
-
- -
-
- -

◆ group

- -
-
- - - - -
struct hwloc_obj_attr_u::hwloc_group_attr_s hwloc_obj_attr_u::group
-
- -
-
- -

◆ numanode

- -
-
- - - - -
struct hwloc_obj_attr_u::hwloc_numanode_attr_s hwloc_obj_attr_u::numanode
-
- -
-
- -

◆ osdev

- -
-
- - - - -
struct hwloc_obj_attr_u::hwloc_osdev_attr_s hwloc_obj_attr_u::osdev
-
- -
-
- -

◆ pcidev

- -
-
- - - - -
struct hwloc_obj_attr_u::hwloc_pcidev_attr_s hwloc_obj_attr_u::pcidev
-
- -
-
-
The documentation for this union was generated from the following file: -
- - - - - - - - -
-
-Data Structures | -Data Fields
-
-
hwloc_obj_attr_u::hwloc_numanode_attr_s Struct Reference
-
-
- -

#include <hwloc.h>

- - - - -

-Data Structures

struct  hwloc_memory_page_type_s
 
- - - - - - - -

-Data Fields

hwloc_uint64_t local_memory
 
unsigned page_types_len
 
struct hwloc_obj_attr_u::hwloc_numanode_attr_s::hwloc_memory_page_type_s * page_types
 
-

Detailed Description

-

NUMA node-specific Object Attributes.

-

Field Documentation

- -

◆ local_memory

- -
-
- - - - -
hwloc_uint64_t hwloc_obj_attr_u::hwloc_numanode_attr_s::local_memory
-
- -

Local memory (in bytes)

- -
-
- -

◆ page_types

- -
-
- - - - -
struct hwloc_obj_attr_u::hwloc_numanode_attr_s::hwloc_memory_page_type_s * hwloc_obj_attr_u::hwloc_numanode_attr_s::page_types
-
- -
-
- -

◆ page_types_len

- -
-
- - - - -
unsigned hwloc_obj_attr_u::hwloc_numanode_attr_s::page_types_len
-
- -

Size of array page_types.

- -
-
-
The documentation for this struct was generated from the following file: -
- - - - - - - - -
-
-Data Fields
-
-
hwloc_obj_attr_u::hwloc_numanode_attr_s::hwloc_memory_page_type_s Struct Reference
-
-
- -

#include <hwloc.h>

- - - - - - -

-Data Fields

hwloc_uint64_t size
 
hwloc_uint64_t count
 
-

Detailed Description

-

Array of local memory page types, NULL if no local memory and page_types is 0.

-

The array is sorted by increasing size fields. It contains page_types_len slots.

-

Field Documentation

- -

◆ count

- -
-
- - - - -
hwloc_uint64_t hwloc_obj_attr_u::hwloc_numanode_attr_s::hwloc_memory_page_type_s::count
-
- -

Number of pages of this size.

- -
-
- -

◆ size

- -
-
- - - - -
hwloc_uint64_t hwloc_obj_attr_u::hwloc_numanode_attr_s::hwloc_memory_page_type_s::size
-
- -

Size of pages.

- -
-
-
The documentation for this struct was generated from the following file: -
- - - - - - - - -
-
-Data Fields
-
-
hwloc_obj_attr_u::hwloc_cache_attr_s Struct Reference
-
-
- -

#include <hwloc.h>

- - - - - - - - - - - - -

-Data Fields

hwloc_uint64_t size
 
unsigned depth
 
unsigned linesize
 
int associativity
 
hwloc_obj_cache_type_t type
 
-

Detailed Description

-

Cache-specific Object Attributes.

-

Field Documentation

- -

◆ associativity

- -
-
- - - - -
int hwloc_obj_attr_u::hwloc_cache_attr_s::associativity
-
- -

Ways of associativity, -1 if fully associative, 0 if unknown.

- -
-
- -

◆ depth

- -
-
- - - - -
unsigned hwloc_obj_attr_u::hwloc_cache_attr_s::depth
-
- -

Depth of cache (e.g., L1, L2, ...etc.)

- -
-
- -

◆ linesize

- -
-
- - - - -
unsigned hwloc_obj_attr_u::hwloc_cache_attr_s::linesize
-
- -

Cache-line size in bytes. 0 if unknown.

- -
-
- -

◆ size

- -
-
- - - - -
hwloc_uint64_t hwloc_obj_attr_u::hwloc_cache_attr_s::size
-
- -

Size of cache in bytes.

- -
-
- -

◆ type

- -
-
- - - - -
hwloc_obj_cache_type_t hwloc_obj_attr_u::hwloc_cache_attr_s::type
-
- -

Cache type.

- -
-
-
The documentation for this struct was generated from the following file: -
- - - - - - - - -
-
-Data Fields
-
-
hwloc_obj_attr_u::hwloc_group_attr_s Struct Reference
-
-
- -

#include <hwloc.h>

- - - - - - - - - - -

-Data Fields

unsigned depth
 
unsigned kind
 
unsigned subkind
 
unsigned char dont_merge
 
-

Detailed Description

-

Group-specific Object Attributes.

-

Field Documentation

- -

◆ depth

- -
-
- - - - -
unsigned hwloc_obj_attr_u::hwloc_group_attr_s::depth
-
- -

Depth of group object. It may change if intermediate Group objects are added.

- -
-
- -

◆ dont_merge

- -
-
- - - - -
unsigned char hwloc_obj_attr_u::hwloc_group_attr_s::dont_merge
-
- -

Flag preventing groups from being automatically merged with identical parent or children.

- -
-
- -

◆ kind

- -
-
- - - - -
unsigned hwloc_obj_attr_u::hwloc_group_attr_s::kind
-
- -

Internally-used kind of group.

- -
-
- -

◆ subkind

- -
-
- - - - -
unsigned hwloc_obj_attr_u::hwloc_group_attr_s::subkind
-
- -

Internally-used subkind to distinguish different levels of groups with same kind.

- -
-
-
The documentation for this struct was generated from the following file: -
- - - - - - - - -
-
-Data Fields
-
-
hwloc_obj_attr_u::hwloc_pcidev_attr_s Struct Reference
-
-
- -

#include <hwloc.h>

- - - - - - - - - - - - - - - - - - - - - - - - -

-Data Fields

unsigned short domain
 
unsigned char bus
 
unsigned char dev
 
unsigned char func
 
unsigned short class_id
 
unsigned short vendor_id
 
unsigned short device_id
 
unsigned short subvendor_id
 
unsigned short subdevice_id
 
unsigned char revision
 
float linkspeed
 
-

Detailed Description

-

PCI Device specific Object Attributes.

-

Field Documentation

- -

◆ bus

- -
-
- - - - -
unsigned char hwloc_obj_attr_u::hwloc_pcidev_attr_s::bus
-
- -
-
- -

◆ class_id

- -
-
- - - - -
unsigned short hwloc_obj_attr_u::hwloc_pcidev_attr_s::class_id
-
- -
-
- -

◆ dev

- -
-
- - - - -
unsigned char hwloc_obj_attr_u::hwloc_pcidev_attr_s::dev
-
- -
-
- -

◆ device_id

- -
-
- - - - -
unsigned short hwloc_obj_attr_u::hwloc_pcidev_attr_s::device_id
-
- -
-
- -

◆ domain

- -
-
- - - - -
unsigned short hwloc_obj_attr_u::hwloc_pcidev_attr_s::domain
-
- -
-
- -

◆ func

- -
-
- - - - -
unsigned char hwloc_obj_attr_u::hwloc_pcidev_attr_s::func
-
- -
-
- -

◆ linkspeed

- -
-
- - - - -
float hwloc_obj_attr_u::hwloc_pcidev_attr_s::linkspeed
-
- -
-
- -

◆ revision

- -
-
- - - - -
unsigned char hwloc_obj_attr_u::hwloc_pcidev_attr_s::revision
-
- -
-
- -

◆ subdevice_id

- -
-
- - - - -
unsigned short hwloc_obj_attr_u::hwloc_pcidev_attr_s::subdevice_id
-
- -
-
- -

◆ subvendor_id

- -
-
- - - - -
unsigned short hwloc_obj_attr_u::hwloc_pcidev_attr_s::subvendor_id
-
- -
-
- -

◆ vendor_id

- -
-
- - - - -
unsigned short hwloc_obj_attr_u::hwloc_pcidev_attr_s::vendor_id
-
- -
-
-
The documentation for this struct was generated from the following file: -
- - - - - - - - -
-
-Data Fields
-
-
hwloc_obj_attr_u::hwloc_bridge_attr_s Struct Reference
-
-
- -

#include <hwloc.h>

- - - - - - - - - - - - - - - - - - - - - - - - - -

-Data Fields

union {
   struct hwloc_pcidev_attr_s   pci
 
} upstream
 
hwloc_obj_bridge_type_t upstream_type
 
union {
   struct {
      unsigned short   domain
 
      unsigned char   secondary_bus
 
      unsigned char   subordinate_bus
 
   }   pci
 
} downstream
 
hwloc_obj_bridge_type_t downstream_type
 
unsigned depth
 
-

Detailed Description

-

Bridge specific Object Attributes.

-

Field Documentation

- -

◆ depth

- -
-
- - - - -
unsigned hwloc_obj_attr_u::hwloc_bridge_attr_s::depth
-
- -
-
- -

◆ domain

- -
-
- - - - -
unsigned short hwloc_obj_attr_u::hwloc_bridge_attr_s::domain
-
- -
-
- -

◆ 

- -
-
- - - - -
union { ... } hwloc_obj_attr_u::hwloc_bridge_attr_s::downstream
-
- -
-
- -

◆ downstream_type

- -
-
- - - - -
hwloc_obj_bridge_type_t hwloc_obj_attr_u::hwloc_bridge_attr_s::downstream_type
-
- -
-
- -

◆  [1/2]

- -
-
- - - - -
struct { ... } hwloc_obj_attr_u::hwloc_bridge_attr_s::pci
-
- -
-
- -

◆ pci [2/2]

- -
-
- - - - -
struct hwloc_pcidev_attr_s hwloc_obj_attr_u::hwloc_bridge_attr_s::pci
-
- -
-
- -

◆ secondary_bus

- -
-
- - - - -
unsigned char hwloc_obj_attr_u::hwloc_bridge_attr_s::secondary_bus
-
- -
-
- -

◆ subordinate_bus

- -
-
- - - - -
unsigned char hwloc_obj_attr_u::hwloc_bridge_attr_s::subordinate_bus
-
- -
-
- -

◆ 

- -
-
- - - - -
union { ... } hwloc_obj_attr_u::hwloc_bridge_attr_s::upstream
-
- -
-
- -

◆ upstream_type

- -
-
- - - - -
hwloc_obj_bridge_type_t hwloc_obj_attr_u::hwloc_bridge_attr_s::upstream_type
-
- -
-
-
The documentation for this struct was generated from the following file: -
- - - - - - - - -
-
-Data Fields
-
-
hwloc_obj_attr_u::hwloc_osdev_attr_s Struct Reference
-
-
- -

#include <hwloc.h>

- - - - -

-Data Fields

hwloc_obj_osdev_type_t type
 
-

Detailed Description

-

OS Device specific Object Attributes.

-

Field Documentation

- -

◆ type

- -
-
- - - - -
hwloc_obj_osdev_type_t hwloc_obj_attr_u::hwloc_osdev_attr_s::type
-
- -
-
-
The documentation for this struct was generated from the following file: -
- - - - - - - -
-
-Data Fields
-
-
hwloc_info_s Struct Reference
Object Structure and Attributes
-
-
- -

#include <hwloc.h>

- - - - - - -

-Data Fields

char * name
 
char * value
 
-

Detailed Description

-

Object info.

-
See also
Consulting and Adding Key-Value Info Attributes
-

Field Documentation

- -

◆ name

- -
-
- - - - -
char* hwloc_info_s::name
-
- -

Info name.

- -
-
- -

◆ value

- -
-
- - - - -
char* hwloc_info_s::value
-
- -

Info value.

- -
-
-
The documentation for this struct was generated from the following file: -
- - - - - - - -
-
-Data Fields
-
-
hwloc_topology_discovery_support Struct Reference
Topology Detection Configuration and Query
-
-
- -

#include <hwloc.h>

- - - - - - - - - - - - - - -

-Data Fields

unsigned char pu
 
unsigned char numa
 
unsigned char numa_memory
 
unsigned char disallowed_pu
 
unsigned char disallowed_numa
 
unsigned char cpukind_efficiency
 
-

Detailed Description

-

Flags describing actual discovery support for this topology.

-

Field Documentation

- -

◆ cpukind_efficiency

- -
-
- - - - -
unsigned char hwloc_topology_discovery_support::cpukind_efficiency
-
- -

Detecting the efficiency of CPU kinds is supported, see Kinds of CPU cores.

- -
-
- -

◆ disallowed_numa

- -
-
- - - - -
unsigned char hwloc_topology_discovery_support::disallowed_numa
-
- -

Detecting and identifying NUMA nodes that are not available to the current process is supported.

- -
-
- -

◆ disallowed_pu

- -
-
- - - - -
unsigned char hwloc_topology_discovery_support::disallowed_pu
-
- -

Detecting and identifying PU objects that are not available to the current process is supported.

- -
-
- -

◆ numa

- -
-
- - - - -
unsigned char hwloc_topology_discovery_support::numa
-
- -

Detecting the number of NUMA nodes is supported.

- -
-
- -

◆ numa_memory

- -
-
- - - - -
unsigned char hwloc_topology_discovery_support::numa_memory
-
- -

Detecting the amount of memory in NUMA nodes is supported.

- -
-
- -

◆ pu

- -
-
- - - - -
unsigned char hwloc_topology_discovery_support::pu
-
- -

Detecting the number of PU objects is supported.

- -
-
-
The documentation for this struct was generated from the following file: -
- - - - - - - -
-
-Data Fields
-
-
hwloc_topology_cpubind_support Struct Reference
Topology Detection Configuration and Query
-
-
- -

#include <hwloc.h>

- - - - - - - - - - - - - - - - - - - - - - - - -

-Data Fields

unsigned char set_thisproc_cpubind
 
unsigned char get_thisproc_cpubind
 
unsigned char set_proc_cpubind
 
unsigned char get_proc_cpubind
 
unsigned char set_thisthread_cpubind
 
unsigned char get_thisthread_cpubind
 
unsigned char set_thread_cpubind
 
unsigned char get_thread_cpubind
 
unsigned char get_thisproc_last_cpu_location
 
unsigned char get_proc_last_cpu_location
 
unsigned char get_thisthread_last_cpu_location
 
-

Detailed Description

-

Flags describing actual PU binding support for this topology.

-

A flag may be set even if the feature isn't supported in all cases (e.g. binding to random sets of non-contiguous objects).

-

Field Documentation

- -

◆ get_proc_cpubind

- -
-
- - - - -
unsigned char hwloc_topology_cpubind_support::get_proc_cpubind
-
-

Getting the binding of a whole given process is supported.

- -
-
- -

◆ get_proc_last_cpu_location

- -
-
- - - - -
unsigned char hwloc_topology_cpubind_support::get_proc_last_cpu_location
-
-

Getting the last processors where a whole process ran is supported

- -
-
- -

◆ get_thisproc_cpubind

- -
-
- - - - -
unsigned char hwloc_topology_cpubind_support::get_thisproc_cpubind
-
-

Getting the binding of the whole current process is supported.

- -
-
- -

◆ get_thisproc_last_cpu_location

- -
-
- - - - -
unsigned char hwloc_topology_cpubind_support::get_thisproc_last_cpu_location
-
-

Getting the last processors where the whole current process ran is supported

- -
-
- -

◆ get_thisthread_cpubind

- -
-
- - - - -
unsigned char hwloc_topology_cpubind_support::get_thisthread_cpubind
-
-

Getting the binding of the current thread only is supported.

- -
-
- -

◆ get_thisthread_last_cpu_location

- -
-
- - - - -
unsigned char hwloc_topology_cpubind_support::get_thisthread_last_cpu_location
-
-

Getting the last processors where the current thread ran is supported

- -
-
- -

◆ get_thread_cpubind

- -
-
- - - - -
unsigned char hwloc_topology_cpubind_support::get_thread_cpubind
-
-

Getting the binding of a given thread only is supported.

- -
-
- -

◆ set_proc_cpubind

- -
-
- - - - -
unsigned char hwloc_topology_cpubind_support::set_proc_cpubind
-
-

Binding a whole given process is supported.

- -
-
- -

◆ set_thisproc_cpubind

- -
-
- - - - -
unsigned char hwloc_topology_cpubind_support::set_thisproc_cpubind
-
-

Binding the whole current process is supported.

- -
-
- -

◆ set_thisthread_cpubind

- -
-
- - - - -
unsigned char hwloc_topology_cpubind_support::set_thisthread_cpubind
-
-

Binding the current thread only is supported.

- -
-
- -

◆ set_thread_cpubind

- -
-
- - - - -
unsigned char hwloc_topology_cpubind_support::set_thread_cpubind
-
-

Binding a given thread only is supported.

- -
-
-
The documentation for this struct was generated from the following file: -
- - - - - - - -
-
-Data Fields
-
-
hwloc_topology_membind_support Struct Reference
Topology Detection Configuration and Query
-
-
- -

#include <hwloc.h>

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

-Data Fields

unsigned char set_thisproc_membind
 
unsigned char get_thisproc_membind
 
unsigned char set_proc_membind
 
unsigned char get_proc_membind
 
unsigned char set_thisthread_membind
 
unsigned char get_thisthread_membind
 
unsigned char set_area_membind
 
unsigned char get_area_membind
 
unsigned char alloc_membind
 
unsigned char firsttouch_membind
 
unsigned char bind_membind
 
unsigned char interleave_membind
 
unsigned char nexttouch_membind
 
unsigned char migrate_membind
 
unsigned char get_area_memlocation
 
-

Detailed Description

-

Flags describing actual memory binding support for this topology.

-

A flag may be set even if the feature isn't supported in all cases (e.g. binding to random sets of non-contiguous objects).

-

Field Documentation

- -

◆ alloc_membind

- -
-
- - - - -
unsigned char hwloc_topology_membind_support::alloc_membind
-
-

Allocating a bound memory area is supported.

- -
-
- -

◆ bind_membind

- -
-
- - - - -
unsigned char hwloc_topology_membind_support::bind_membind
-
-

Bind policy is supported.

- -
-
- -

◆ firsttouch_membind

- -
-
- - - - -
unsigned char hwloc_topology_membind_support::firsttouch_membind
-
-

First-touch policy is supported.

- -
-
- -

◆ get_area_membind

- -
-
- - - - -
unsigned char hwloc_topology_membind_support::get_area_membind
-
-

Getting the binding of a given memory area is supported.

- -
-
- -

◆ get_area_memlocation

- -
-
- - - - -
unsigned char hwloc_topology_membind_support::get_area_memlocation
-
-

Getting the last NUMA nodes where a memory area was allocated is supported

- -
-
- -

◆ get_proc_membind

- -
-
- - - - -
unsigned char hwloc_topology_membind_support::get_proc_membind
-
-

Getting the binding of a whole given process is supported.

- -
-
- -

◆ get_thisproc_membind

- -
-
- - - - -
unsigned char hwloc_topology_membind_support::get_thisproc_membind
-
-

Getting the binding of the whole current process is supported.

- -
-
- -

◆ get_thisthread_membind

- -
-
- - - - -
unsigned char hwloc_topology_membind_support::get_thisthread_membind
-
-

Getting the binding of the current thread only is supported.

- -
-
- -

◆ interleave_membind

- -
-
- - - - -
unsigned char hwloc_topology_membind_support::interleave_membind
-
-

Interleave policy is supported.

- -
-
- -

◆ migrate_membind

- -
-
- - - - -
unsigned char hwloc_topology_membind_support::migrate_membind
-
-

Migration flags is supported.

- -
-
- -

◆ nexttouch_membind

- -
-
- - - - -
unsigned char hwloc_topology_membind_support::nexttouch_membind
-
-

Next-touch migration policy is supported.

- -
-
- -

◆ set_area_membind

- -
-
- - - - -
unsigned char hwloc_topology_membind_support::set_area_membind
-
-

Binding a given memory area is supported.

- -
-
- -

◆ set_proc_membind

- -
-
- - - - -
unsigned char hwloc_topology_membind_support::set_proc_membind
-
-

Binding a whole given process is supported.

- -
-
- -

◆ set_thisproc_membind

- -
-
- - - - -
unsigned char hwloc_topology_membind_support::set_thisproc_membind
-
-

Binding the whole current process is supported.

- -
-
- -

◆ set_thisthread_membind

- -
-
- - - - -
unsigned char hwloc_topology_membind_support::set_thisthread_membind
-
-

Binding the current thread only is supported.

- -
-
-
The documentation for this struct was generated from the following file: -
- - - - - - - -
-
-Data Fields
-
-
hwloc_topology_misc_support Struct Reference
Topology Detection Configuration and Query
-
-
- -

#include <hwloc.h>

- - - - -

-Data Fields

unsigned char imported_support
 
-

Detailed Description

-

Flags describing miscellaneous features.

-

Field Documentation

- -

◆ imported_support

- -
-
- - - - -
unsigned char hwloc_topology_misc_support::imported_support
-
-

Support was imported when importing another topology, see HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT.

- -
-
-
The documentation for this struct was generated from the following file: -
- - - - - - - -
-
-Data Fields
-
-
hwloc_topology_support Struct Reference
Topology Detection Configuration and Query
-
-
- -

#include <hwloc.h>

- - - - - - - - - - -

-Data Fields

struct hwloc_topology_discovery_support * discovery
 
struct hwloc_topology_cpubind_support * cpubind
 
struct hwloc_topology_membind_support * membind
 
struct hwloc_topology_misc_support * misc
 
-

Detailed Description

-

Set of flags describing actual support for this topology.

-

This is retrieved with hwloc_topology_get_support() and will be valid until the topology object is destroyed. Note: the values are correct only after discovery.

-

Field Documentation

- -

◆ cpubind

- -
-
- - - - -
struct hwloc_topology_cpubind_support* hwloc_topology_support::cpubind
-
- -
-
- -

◆ discovery

- -
-
- - - - -
struct hwloc_topology_discovery_support* hwloc_topology_support::discovery
-
- -
-
- -

◆ membind

- -
-
- - - - -
struct hwloc_topology_membind_support* hwloc_topology_support::membind
-
- -
-
- -

◆ misc

- -
-
- - - - -
struct hwloc_topology_misc_support* hwloc_topology_support::misc
-
- -
-
-
The documentation for this struct was generated from the following file: -
- - - - - - - -
-
-Data Fields
-
-
hwloc_distances_s Struct Reference
Retrieve distances between objects
-
-
- -

#include <distances.h>

- - - - - - - - - - -

-Data Fields

unsigned nbobjs
 
hwloc_obj_t * objs
 
unsigned long kind
 
hwloc_uint64_t * values
 
-

Detailed Description

-

Matrix of distances between a set of objects.

-

This matrix often contains latencies between NUMA nodes (as reported in the System Locality Distance Information Table (SLIT) in the ACPI specification), which may or may not be physically accurate. It corresponds to the latency for accessing the memory of one node from a core in another node. The corresponding kind is HWLOC_DISTANCES_KIND_FROM_OS | HWLOC_DISTANCES_KIND_FROM_USER. The name of this distances structure is "NUMALatency". Others distance structures include and "XGMIBandwidth", "XGMIHops", "XeLinkBandwidth" and "NVLinkBandwidth".

-

The matrix may also contain bandwidths between random sets of objects, possibly provided by the user, as specified in the kind attribute.

-

Pointers objs and values should not be replaced, reallocated, freed, etc. However callers are allowed to modify kind as well as the contents of objs and values arrays. For instance, if there is a single NUMA node per Package, hwloc_get_obj_with_same_locality() may be used to convert between them and replace NUMA nodes in the objs array with the corresponding Packages. See also hwloc_distances_transform() for applying some transformations to the structure.

-

Field Documentation

- -

◆ kind

- -
-
- - - - -
unsigned long hwloc_distances_s::kind
-
- -

OR'ed set of hwloc_distances_kind_e.

- -
-
- -

◆ nbobjs

- -
-
- - - - -
unsigned hwloc_distances_s::nbobjs
-
- -

Number of objects described by the distance matrix.

- -
-
- -

◆ objs

- -
-
- - - - -
hwloc_obj_t* hwloc_distances_s::objs
-
- -

Array of objects described by the distance matrix. These objects are not in any particular order, see hwloc_distances_obj_index() and hwloc_distances_obj_pair_values() for easy ways to find objects in this array and their corresponding values.

- -
-
- -

◆ values

- -
-
- - - - -
hwloc_uint64_t* hwloc_distances_s::values
-
- -

Matrix of distances between objects, stored as a one-dimension array.

-

Distance from i-th to j-th object is stored in slot i*nbobjs+j. The meaning of the value depends on the kind attribute.

- -
-
-
The documentation for this struct was generated from the following file: -
- - - - - - - -
-
-Data Structures | -Data Fields
-
-
hwloc_location Struct Reference
Comparing memory node attributes for finding where to allocate on
-
-
- -

#include <memattrs.h>

- - - - -

-Data Structures

union  hwloc_location_u
 
- - - - - -

-Data Fields

enum hwloc_location_type_e type
 
union hwloc_location::hwloc_location_u location
 
-

Detailed Description

-

Where to measure attributes from.

-

Field Documentation

- -

◆ location

- -
-
- - - - -
union hwloc_location::hwloc_location_u hwloc_location::location
-
- -
-
- -

◆ type

- -
-
- - - - -
enum hwloc_location_type_e hwloc_location::type
-
- -

Type of location.

- -
-
-
The documentation for this struct was generated from the following file: -
- - - - - - - - -
-
-Data Fields
-
-
hwloc_location::hwloc_location_u Union Reference
-
-
- -

#include <memattrs.h>

- - - - - - -

-Data Fields

hwloc_cpuset_t cpuset
 
hwloc_obj_t object
 
-

Detailed Description

-

Actual location.

-

Field Documentation

- -

◆ cpuset

- -
-
- - - - -
hwloc_cpuset_t hwloc_location::hwloc_location_u::cpuset
-
- -

Location as a cpuset, when the location type is HWLOC_LOCATION_TYPE_CPUSET.

- -
-
- -

◆ object

- -
-
- - - - -
hwloc_obj_t hwloc_location::hwloc_location_u::object
-
- -

Location as an object, when the location type is HWLOC_LOCATION_TYPE_OBJECT.

- -
-
-
The documentation for this union was generated from the following file: -
- - - - - - - -
-
-Data Fields
-
-
hwloc_cl_device_topology_amd Union Reference
-
-
- -

#include <opencl.h>

- - - - - - - - - - - - - - - - - - - - - - -

-Data Fields

struct {
   cl_uint   type
 
   cl_uint   data [5]
 
} raw
 
struct {
   cl_uint   type
 
   cl_char   unused [17]
 
   cl_char   bus
 
   cl_char   device
 
   cl_char   function
 
} pcie
 
-

Field Documentation

- -

◆ bus

- -
-
- - - - -
cl_char hwloc_cl_device_topology_amd::bus
-
- -
-
- -

◆ data

- -
-
- - - - -
cl_uint hwloc_cl_device_topology_amd::data[5]
-
- -
-
- -

◆ device

- -
-
- - - - -
cl_char hwloc_cl_device_topology_amd::device
-
- -
-
- -

◆ function

- -
-
- - - - -
cl_char hwloc_cl_device_topology_amd::function
-
- -
-
- -

◆ 

- -
-
- - - - -
struct { ... } hwloc_cl_device_topology_amd::pcie
-
- -
-
- -

◆ 

- -
-
- - - - -
struct { ... } hwloc_cl_device_topology_amd::raw
-
- -
-
- -

◆ type

- -
-
- - - - -
cl_uint hwloc_cl_device_topology_amd::type
-
- -
-
- -

◆ unused

- -
-
- - - - -
cl_char hwloc_cl_device_topology_amd::unused[17]
-
- -
-
-
The documentation for this union was generated from the following file: -
- - - - - - - -
-
-Data Structures | -Data Fields
-
-
hwloc_topology_diff_obj_attr_u Union Reference
Topology differences
-
-
- -

#include <diff.h>

- - - - - - - - -

-Data Structures

struct  hwloc_topology_diff_obj_attr_generic_s
 
struct  hwloc_topology_diff_obj_attr_string_s
 
struct  hwloc_topology_diff_obj_attr_uint64_s
 
- - - - - - - -

-Data Fields

struct hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_generic_s generic
 
struct hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s uint64
 
struct hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s string
 
-

Detailed Description

-

One object attribute difference.

-

Field Documentation

- -

◆ generic

- -
-
- - - - -
struct hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_generic_s hwloc_topology_diff_obj_attr_u::generic
-
- -
-
- -

◆ string

- -
-
- - - - -
struct hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s hwloc_topology_diff_obj_attr_u::string
-
- -
-
- -

◆ uint64

- -
-
- - - - -
struct hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s hwloc_topology_diff_obj_attr_u::uint64
-
- -
-
-
The documentation for this union was generated from the following file: -
- - - - - - - - -
-
-Data Fields
-
-
hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_generic_s Struct Reference
-
-
- -

#include <diff.h>

- - - - -

-Data Fields

hwloc_topology_diff_obj_attr_type_t type
 
-

Field Documentation

- -

◆ type

- -
-
- - - - -
hwloc_topology_diff_obj_attr_type_t hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_generic_s::type
-
- -
-
-
The documentation for this struct was generated from the following file: -
- - - - - - - - -
-
-Data Fields
-
-
hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s Struct Reference
-
-
- -

#include <diff.h>

- - - - - - - - - - -

-Data Fields

hwloc_topology_diff_obj_attr_type_t type
 
hwloc_uint64_t index
 
hwloc_uint64_t oldvalue
 
hwloc_uint64_t newvalue
 
-

Detailed Description

-

Integer attribute modification with an optional index.

-

Field Documentation

- -

◆ index

- -
-
- - - - -
hwloc_uint64_t hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s::index
-
- -
-
- -

◆ newvalue

- -
-
- - - - -
hwloc_uint64_t hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s::newvalue
-
- -
-
- -

◆ oldvalue

- -
-
- - - - -
hwloc_uint64_t hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s::oldvalue
-
- -
-
- -

◆ type

- -
-
- - - - -
hwloc_topology_diff_obj_attr_type_t hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s::type
-
- -
-
-
The documentation for this struct was generated from the following file: -
- - - - - - - - -
-
-Data Fields
-
-
hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s Struct Reference
-
-
- -

#include <diff.h>

- - - - - - - - - - -

-Data Fields

hwloc_topology_diff_obj_attr_type_t type
 
char * name
 
char * oldvalue
 
char * newvalue
 
-

Detailed Description

-

String attribute modification with an optional name.

-

Field Documentation

- -

◆ name

- -
-
- - - - -
char* hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s::name
-
- -
-
- -

◆ newvalue

- -
-
- - - - -
char* hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s::newvalue
-
- -
-
- -

◆ oldvalue

- -
-
- - - - -
char* hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s::oldvalue
-
- -
-
- -

◆ type

- -
-
- - - - -
hwloc_topology_diff_obj_attr_type_t hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s::type
-
- -
-
-
The documentation for this struct was generated from the following file: -
- - - - - - - -
-
-Data Structures | -Data Fields
-
-
hwloc_topology_diff_u Union Reference
Topology differences
-
-
- -

#include <diff.h>

- - - - - - - - -

-Data Structures

struct  hwloc_topology_diff_generic_s
 
struct  hwloc_topology_diff_obj_attr_s
 
struct  hwloc_topology_diff_too_complex_s
 
- - - - - - - -

-Data Fields

struct hwloc_topology_diff_u::hwloc_topology_diff_generic_s generic
 
struct hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s obj_attr
 
struct hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s too_complex
 
-

Detailed Description

-

One element of a difference list between two topologies.

-

Field Documentation

- -

◆ generic

- -
-
- - - - -
struct hwloc_topology_diff_u::hwloc_topology_diff_generic_s hwloc_topology_diff_u::generic
-
- -
-
- -

◆ obj_attr

- -
-
- - - - -
struct hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s hwloc_topology_diff_u::obj_attr
-
- -
-
- -

◆ too_complex

- -
-
- - - - -
struct hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s hwloc_topology_diff_u::too_complex
-
- -
-
-
The documentation for this union was generated from the following file: -
- - - - - - - - -
-
-Data Fields
-
-
hwloc_topology_diff_u::hwloc_topology_diff_generic_s Struct Reference
-
-
- -

#include <diff.h>

- - - - - - -

-Data Fields

hwloc_topology_diff_type_t type
 
union hwloc_topology_diff_u * next
 
-

Field Documentation

- -

◆ next

- -
-
- - - - -
union hwloc_topology_diff_u* hwloc_topology_diff_u::hwloc_topology_diff_generic_s::next
-
- -
-
- -

◆ type

- -
-
- - - - -
hwloc_topology_diff_type_t hwloc_topology_diff_u::hwloc_topology_diff_generic_s::type
-
- -
-
-
The documentation for this struct was generated from the following file: -
- - - - - - - - -
-
-Data Fields
-
-
hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s Struct Reference
-
-
- -

#include <diff.h>

- - - - - - - - - - - - -

-Data Fields

hwloc_topology_diff_type_t type
 
union hwloc_topology_diff_u * next
 
int obj_depth
 
unsigned obj_index
 
union hwloc_topology_diff_obj_attr_u diff
 
-

Field Documentation

- -

◆ diff

- -
-
- - - - -
union hwloc_topology_diff_obj_attr_u hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s::diff
-
- -
-
- -

◆ next

- -
-
- - - - -
union hwloc_topology_diff_u* hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s::next
-
- -
-
- -

◆ obj_depth

- -
-
- - - - -
int hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s::obj_depth
-
- -
-
- -

◆ obj_index

- -
-
- - - - -
unsigned hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s::obj_index
-
- -
-
- -

◆ type

- -
-
- - - - -
hwloc_topology_diff_type_t hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s::type
-
- -
-
-
The documentation for this struct was generated from the following file: -
- - - - - - - - -
-
-Data Fields
-
-
hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s Struct Reference
-
-
- -

#include <diff.h>

- - - - - - - - - - -

-Data Fields

hwloc_topology_diff_type_t type
 
union hwloc_topology_diff_u * next
 
int obj_depth
 
unsigned obj_index
 
-

Field Documentation

- -

◆ next

- -
-
- - - - -
union hwloc_topology_diff_u* hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s::next
-
- -
-
- -

◆ obj_depth

- -
-
- - - - -
int hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s::obj_depth
-
- -
-
- -

◆ obj_index

- -
-
- - - - -
unsigned hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s::obj_index
-
- -
-
- -

◆ type

- -
-
- - - - -
hwloc_topology_diff_type_t hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s::type
-
- -
-
-
The documentation for this struct was generated from the following file: -
- - - - - - - -
-
-Data Fields
-
-
hwloc_disc_component Struct Reference
Components and Plugins: Discovery components
-
-
- -

#include <plugins.h>

- - - - - - - - - - - - - - -

-Data Fields

const char * name
 
unsigned phases
 
unsigned excluded_phases
 
struct hwloc_backend *(* instantiate )(struct hwloc_topology *topology, struct hwloc_disc_component *component, unsigned excluded_phases, const void *data1, const void *data2, const void *data3)
 
unsigned priority
 
unsigned enabled_by_default
 
-

Detailed Description

-

Discovery component structure.

-

This is the major kind of components, taking care of the discovery. They are registered by generic components, either statically-built or as plugins.

-

Field Documentation

- -

◆ enabled_by_default

- -
-
- - - - -
unsigned hwloc_disc_component::enabled_by_default
-
- -

Enabled by default. If unset, if will be disabled unless explicitly requested.

- -
-
- -

◆ excluded_phases

- -
-
- - - - -
unsigned hwloc_disc_component::excluded_phases
-
- -

Component phases to exclude, as an OR'ed set of hwloc_disc_phase_t.

-

For a GLOBAL component, this usually includes all other phases (~UL).

-

Other components only exclude types that may bring conflicting topology information. MISC components should likely not be excluded since they usually bring non-primary additional information.

- -
-
- -

◆ instantiate

- -
-
- - - - -
struct hwloc_backend*(* hwloc_disc_component::instantiate) (struct hwloc_topology *topology, struct hwloc_disc_component *component, unsigned excluded_phases, const void *data1, const void *data2, const void *data3)
-
- -

Instantiate callback to create a backend from the component. Parameters data1, data2, data3 are NULL except for components that have special enabling routines such as hwloc_topology_set_xml().

- -
-
- -

◆ name

- -
-
- - - - -
const char* hwloc_disc_component::name
-
- -

Name. If this component is built as a plugin, this name does not have to match the plugin filename.

- -
-
- -

◆ phases

- -
-
- - - - -
unsigned hwloc_disc_component::phases
-
- -

Discovery phases performed by this component. OR'ed set of hwloc_disc_phase_t.

- -
-
- -

◆ priority

- -
-
- - - - -
unsigned hwloc_disc_component::priority
-
- -

Component priority. Used to sort topology->components, higher priority first. Also used to decide between two components with the same name.

-

Usual values are 50 for native OS (or platform) components, 45 for x86, 40 for no-OS fallback, 30 for global components (xml, synthetic), 20 for pci, 10 for other misc components (opencl etc.).

- -
-
-
The documentation for this struct was generated from the following file: -
- - - - - - - -
-
-Data Fields
-
-
hwloc_disc_status Struct Reference
Components and Plugins: Discovery backends
-
-
- -

#include <plugins.h>

- - - - - - - - -

-Data Fields

hwloc_disc_phase_t phase
 
unsigned excluded_phases
 
unsigned long flags
 
-

Detailed Description

-

Discovery status structure.

-

Used by the core and backends to inform about what has been/is being done during the discovery process.

-

Field Documentation

- -

◆ excluded_phases

- -
-
- - - - -
unsigned hwloc_disc_status::excluded_phases
-
- -

Dynamically excluded phases. If a component decides during discovery that some phases are no longer needed.

- -
-
- -

◆ flags

- -
-
- - - - -
unsigned long hwloc_disc_status::flags
-
- -

OR'ed set of hwloc_disc_status_flag_e.

- -
-
- -

◆ phase

- -
-
- - - - -
hwloc_disc_phase_t hwloc_disc_status::phase
-
- -

The current discovery phase that is performed. Must match one of the phases in the component phases field.

- -
-
-
The documentation for this struct was generated from the following file: -
- - - - - - - -
-
-Data Fields
-
-
hwloc_backend Struct Reference
Components and Plugins: Discovery backends
-
-
- -

#include <plugins.h>

- - - - - - - - - - - - - - - - -

-Data Fields

unsigned phases
 
unsigned long flags
 
int is_thissystem
 
void * private_data
 
void(* disable )(struct hwloc_backend *backend)
 
int(* discover )(struct hwloc_backend *backend, struct hwloc_disc_status *status)
 
int(* get_pci_busid_cpuset )(struct hwloc_backend *backend, struct hwloc_pcidev_attr_s *busid, hwloc_bitmap_t cpuset)
 
-

Detailed Description

-

Discovery backend structure.

-

A backend is the instantiation of a discovery component. When a component gets enabled for a topology, its instantiate() callback creates a backend.

-

hwloc_backend_alloc() initializes all fields to default values that the component may change (except "component" and "next") before enabling the backend with hwloc_backend_enable().

-

Most backends assume that the topology is_thissystem flag is set because they talk to the underlying operating system. However they may still be used in topologies without the is_thissystem flag for debugging reasons. In practice, they are usually auto-disabled in such cases (excluded by xml or synthetic backends, or by environment variables when changing the Linux fsroot or the x86 cpuid path).

-

Field Documentation

- -

◆ disable

- -
-
- - - - -
void(* hwloc_backend::disable) (struct hwloc_backend *backend)
-
- -

Callback for freeing the private_data. May be NULL.

- -
-
- -

◆ discover

- -
-
- - - - -
int(* hwloc_backend::discover) (struct hwloc_backend *backend, struct hwloc_disc_status *status)
-
- -

Main discovery callback. returns -1 on error, either because it couldn't add its objects ot the existing topology, or because of an actual discovery/gathering failure. May be NULL.

- -
-
- -

◆ flags

- -
-
- - - - -
unsigned long hwloc_backend::flags
-
- -

Backend flags, currently always 0.

- -
-
- -

◆ get_pci_busid_cpuset

- -
-
- - - - -
int(* hwloc_backend::get_pci_busid_cpuset) (struct hwloc_backend *backend, struct hwloc_pcidev_attr_s *busid, hwloc_bitmap_t cpuset)
-
- -

Callback to retrieve the locality of a PCI object. Called by the PCI core when attaching PCI hierarchy to CPU objects. May be NULL.

- -
-
- -

◆ is_thissystem

- -
-
- - - - -
int hwloc_backend::is_thissystem
-
- -

Backend-specific 'is_thissystem' property. Set to 0 if the backend disables the thissystem flag for this topology (e.g. loading from xml or synthetic string, or using a different fsroot on Linux, or a x86 CPUID dump). Set to -1 if the backend doesn't care (default).

- -
-
- -

◆ phases

- -
-
- - - - -
unsigned hwloc_backend::phases
-
- -

Discovery phases performed by this component, possibly without some of them if excluded by other components. OR'ed set of hwloc_disc_phase_t.

- -
-
- -

◆ private_data

- -
-
- - - - -
void* hwloc_backend::private_data
-
- -

Backend private data, or NULL if none.

- -
-
-
The documentation for this struct was generated from the following file: -
- - - - - - - -
-
-Data Fields
-
-
hwloc_component Struct Reference
Components and Plugins: Generic components
-
-
- -

#include <plugins.h>

- - - - - - - - - - - - - - -

-Data Fields

unsigned abi
 
int(* init )(unsigned long flags)
 
void(* finalize )(unsigned long flags)
 
hwloc_component_type_t type
 
unsigned long flags
 
void * data
 
-

Detailed Description

-

Generic component structure.

-

Generic components structure, either statically listed by configure in static-components.h or dynamically loaded as a plugin.

-

Field Documentation

- -

◆ abi

- -
-
- - - - -
unsigned hwloc_component::abi
-
- -

Component ABI version, set to HWLOC_COMPONENT_ABI.

- -
-
- -

◆ data

- -
-
- - - - -
void* hwloc_component::data
-
- -

Component data, pointing to a struct hwloc_disc_component or struct hwloc_xml_component.

- -
-
- -

◆ finalize

- -
-
- - - - -
void(* hwloc_component::finalize) (unsigned long flags)
-
- -

Process-wide component termination callback.

-

This optional callback is called after unregistering the component from the hwloc core (before unloading the plugin).

-

flags is always 0 for now.

-
Note
If the component uses ltdl for loading its own plugins, it should load/unload them only in init() and finalize(), to avoid race conditions with hwloc's use of ltdl.
- -
-
- -

◆ flags

- -
-
- - - - -
unsigned long hwloc_component::flags
-
- -

Component flags, unused for now.

- -
-
- -

◆ init

- -
-
- - - - -
int(* hwloc_component::init) (unsigned long flags)
-
- -

Process-wide component initialization callback.

-

This optional callback is called when the component is registered to the hwloc core (after loading the plugin).

-

When the component is built as a plugin, this callback should call hwloc_check_plugin_namespace() and return an negative error code on error.

-

flags is always 0 for now.

-
Returns
0 on success, or a negative code on error.
-
Note
If the component uses ltdl for loading its own plugins, it should load/unload them only in init() and finalize(), to avoid race conditions with hwloc's use of ltdl.
- -
-
- -

◆ type

- -
-
- - - - -
hwloc_component_type_t hwloc_component::type
-
- -

Component type.

- -
-
-
The documentation for this struct was generated from the following file: -
- - - - - - - -
-
-
Hardware Locality (hwloc) Introduction
-
-
-

Portable abstraction of hierarchical architectures for high-performance computing

-
-

-

- See also Further Reading -or the Related pages tab above - for links to more sections about hwloc concepts. -
-

-

-

-

-

-hwloc Summary

-

hwloc provides command line tools and a C API to obtain the hierarchical map of key computing elements within a node, such as: NUMA memory nodes, shared caches, processor packages, dies and cores, processing units (logical processors or "threads") and even I/O devices. hwloc also gathers various attributes such as cache and memory information, and is portable across a variety of different operating systems and platforms.

-

hwloc primarily aims at helping high-performance computing (HPC) applications, but is also applicable to any project seeking to exploit code and/or data locality on modern computing platforms.

-

hwloc supports the following operating systems:

-
    -
  • -Linux (including old kernels not having sysfs topology information, with knowledge of cpusets, ScaleMP vSMP support, etc.) on all supported hardware, including Intel Xeon Phi and NumaScale NumaConnect.
    • -
  • -Solaris (with support for processor sets and logical domains)
    • -
  • -AIX
    • -
  • -Darwin / OS X
    • -
  • -FreeBSD and its variants (such as kFreeBSD/GNU)
    • -
  • -NetBSD
    • -
  • -HP-UX
    • -
  • -Microsoft Windows
    • -
  • -IBM BlueGene/Q Compute Node Kernel (CNK)
    • -
-

Since it uses standard Operating System information, hwloc's support is mostly independant from the processor type (x86, powerpc, ...) and just relies on the Operating System support. The main exception is BSD operating systems (NetBSD, FreeBSD, etc.) because they do not provide support topology information, hence hwloc uses an x86-only CPUID-based backend (which can be used for other OSes too, see the Components and plugins section).

-

To check whether hwloc works on a particular machine, just try to build it and run lstopo or lstopo-no-graphics. If some things do not look right (e.g. bogus or missing cache information), see Questions and Bugs.

-

hwloc only reports the number of processors on unsupported operating systems; no topology information is available.

-

For development and debugging purposes, hwloc also offers the ability to work on "fake" topologies:

- -

hwloc can display the topology in a human-readable format, either in graphical mode (X11), or by exporting in one of several different formats, including: plain text, LaTeX tikzpicture, PDF, PNG, and FIG (see Command-line Examples below). Note that some of the export formats require additional support libraries.

-

hwloc offers a programming interface for manipulating topologies and objects. It also brings a powerful CPU bitmap API that is used to describe topology objects location on physical/logical processors. See the Programming Interface below. It may also be used to binding applications onto certain cores or memory nodes. Several utility programs are also provided to ease command-line manipulation of topology objects, binding of processes, and so on.

-

Perl bindings are available from Bernd Kallies on CPAN.

-

Python bindings are available from Guy Streeter:

-

-

-

-

-hwloc Installation

-

The generic installation procedure for both hwloc and netloc is described in Installation.

-

The hwloc command-line tool "lstopo" produces human-readable topology maps, as mentioned above. It can also export maps to the "fig" file format. Support for PDF, Postscript, and PNG exporting is provided if the "Cairo" development package (usually cairo-devel or libcairo2-dev) can be found in "lstopo" when hwloc is configured and build.

-

The hwloc core may also benefit from the following development packages:

    -
  • -

    libpciaccess for full I/O device discovery (libpciaccess-devel or libpciaccess-dev package). On Linux, PCI discovery may still be performed (without vendor/device names) even if libpciaccess cannot be used.

    -

    -
    • -
  • -AMD or NVIDIA OpenCL implementations for OpenCL device discovery.
    • -
  • -the NVIDIA CUDA Toolkit for CUDA device discovery. See How do I enable CUDA and select which CUDA version to use?.
    • -
  • -the NVIDIA Management Library (NVML) for NVML device discovery. It is included in CUDA since version 8.0. Older NVML releases were available within the NVIDIA GPU Deployment Kit from https://developer.nvidia.com/gpu-deployment-kit .
    • -
  • -the NV-CONTROL X extension library (NVCtrl) for NVIDIA display discovery. The relevant development package is usually libXNVCtrl-devel or libxnvctrl-dev. It is also available within nvidia-settings from ftp://download.nvidia.com/XFree86/nvidia-settings/ and https://github.com/NVIDIA/nvidia-settings/ .
    • -
  • -the AMD ROCm SMI library for RSMI device discovery. The relevant development package is usually rocm-smi-lib64 or librocm-smi-dev. See How do I enable ROCm SMI and select which version to use?.
    • -
  • -the oneAPI Level Zero library. The relevant development package is usually level-zero-dev or level-zero-devel.
    • -
  • -libxml2 for full XML import/export support (otherwise, the internal minimalistic parser will only be able to import XML files that were exported by the same hwloc release). See Importing and exporting topologies from/to XML files for details. The relevant development package is usually libxml2-devel or libxml2-dev.
    • -
  • -libudev on Linux for easier discovery of OS device information (otherwise hwloc will try to manually parse udev raw files). The relevant development package is usually libudev-devel or libudev-dev.
    • -
  • -libtool's ltdl library for dynamic plugin loading if the native dlopen cannot be used. The relevant development package is usually libtool-ltdl-devel or libltdl-dev.
    • -
-

PCI and XML support may be statically built inside the main hwloc library, or as separate dynamically-loaded plugins (see the Components and plugins section).

-

Note that because of the possibility of GPL taint, the pciutils library libpci will not be used (remember that hwloc is BSD-licensed).

-

-

-

-

-Command-line Examples

-

On a 4-package 2-core machine with hyper-threading, the lstopo tool may show the following graphical output:

-
- -
-

Here's the equivalent output in textual form:

-
Machine
-  NUMANode L#0 (P#0)
-  Package L#0 + L3 L#0 (4096KB)
-    L2 L#0 (1024KB) + L1 L#0 (16KB) + Core L#0
-      PU L#0 (P#0)
-      PU L#1 (P#8)
-    L2 L#1 (1024KB) + L1 L#1 (16KB) + Core L#1
-      PU L#2 (P#4)
-      PU L#3 (P#12)
-  Package L#1 + L3 L#1 (4096KB)
-    L2 L#2 (1024KB) + L1 L#2 (16KB) + Core L#2
-      PU L#4 (P#1)
-      PU L#5 (P#9)
-    L2 L#3 (1024KB) + L1 L#3 (16KB) + Core L#3
-      PU L#6 (P#5)
-      PU L#7 (P#13)
-  Package L#2 + L3 L#2 (4096KB)
-    L2 L#4 (1024KB) + L1 L#4 (16KB) + Core L#4
-      PU L#8 (P#2)
-      PU L#9 (P#10)
-    L2 L#5 (1024KB) + L1 L#5 (16KB) + Core L#5
-      PU L#10 (P#6)
-      PU L#11 (P#14)
-  Package L#3 + L3 L#3 (4096KB)
-    L2 L#6 (1024KB) + L1 L#6 (16KB) + Core L#6
-      PU L#12 (P#3)
-      PU L#13 (P#11)
-    L2 L#7 (1024KB) + L1 L#7 (16KB) + Core L#7
-      PU L#14 (P#7)
-      PU L#15 (P#15)
-

Note that there is also an equivalent output in XML that is meant for exporting/importing topologies but it is hardly readable to human-beings (see Importing and exporting topologies from/to XML files for details).

-

On a 4-package 2-core Opteron NUMA machine (with two core cores disallowed by the administrator), the lstopo tool may show the following graphical output (with --disallowed for displaying disallowed objects):

-
- -
-

Here's the equivalent output in textual form:

-
Machine (32GB total)
-  Package L#0
-    NUMANode L#0 (P#0 8190MB)
-    L2 L#0 (1024KB) + L1 L#0 (64KB) + Core L#0 + PU L#0 (P#0)
-    L2 L#1 (1024KB) + L1 L#1 (64KB) + Core L#1 + PU L#1 (P#1)
-  Package L#1
-    NUMANode L#1 (P#1 8192MB)
-    L2 L#2 (1024KB) + L1 L#2 (64KB) + Core L#2 + PU L#2 (P#2)
-    L2 L#3 (1024KB) + L1 L#3 (64KB) + Core L#3 + PU L#3 (P#3)
-  Package L#2
-    NUMANode L#2 (P#2 8192MB)
-    L2 L#4 (1024KB) + L1 L#4 (64KB) + Core L#4 + PU L#4 (P#4)
-    L2 L#5 (1024KB) + L1 L#5 (64KB) + Core L#5 + PU L#5 (P#5)
-  Package L#3
-    NUMANode L#3 (P#3 8192MB)
-    L2 L#6 (1024KB) + L1 L#6 (64KB) + Core L#6 + PU L#6 (P#6)
-    L2 L#7 (1024KB) + L1 L#7 (64KB) + Core L#7 + PU L#7 (P#7)
-

On a 2-package quad-core Xeon (pre-Nehalem, with 2 dual-core dies into each package):

-
- -
-

Here's the same output in textual form:

-
Machine (total 16GB)
-  NUMANode L#0 (P#0 16GB)
-  Package L#0
-    L2 L#0 (4096KB)
-      L1 L#0 (32KB) + Core L#0 + PU L#0 (P#0)
-      L1 L#1 (32KB) + Core L#1 + PU L#1 (P#4)
-    L2 L#1 (4096KB)
-      L1 L#2 (32KB) + Core L#2 + PU L#2 (P#2)
-      L1 L#3 (32KB) + Core L#3 + PU L#3 (P#6)
-  Package L#1
-    L2 L#2 (4096KB)
-      L1 L#4 (32KB) + Core L#4 + PU L#4 (P#1)
-      L1 L#5 (32KB) + Core L#5 + PU L#5 (P#5)
-    L2 L#3 (4096KB)
-      L1 L#6 (32KB) + Core L#6 + PU L#6 (P#3)
-      L1 L#7 (32KB) + Core L#7 + PU L#7 (P#7)
-

-

-

-

-Programming Interface

-

The basic interface is available in hwloc.h. Some higher-level functions are available in hwloc/helper.h to reduce the need to manually manipulate objects and follow links between them. Documentation for all these is provided later in this document. Developers may also want to look at hwloc/inlines.h which contains the actual inline code of some hwloc.h routines, and at this document, which provides good higher-level topology traversal examples.

-

To precisely define the vocabulary used by hwloc, a Terms and Definitions section is available and should probably be read first.

-

Each hwloc object contains a cpuset describing the list of processing units that it contains. These bitmaps may be used for CPU binding and Memory binding. hwloc offers an extensive bitmap manipulation interface in hwloc/bitmap.h.

-

Moreover, hwloc also comes with additional helpers for interoperability with several commonly used environments. See the Interoperability With Other Software section for details.

-

The complete API documentation is available in a full set of HTML pages, man pages, and self-contained PDF files (formatted for both both US letter and A4 formats) in the source tarball in doc/doxygen-doc/.

-

NOTE: If you are building the documentation from a Git clone, you will need to have Doxygen and pdflatex installed – the documentation will be built during the normal "make" process. The documentation is installed during "make install" to $prefix/share/doc/hwloc/ and your systems default man page tree (under $prefix, of course).

-

-Portability

-

Operating System have varying support for CPU and memory binding, e.g. while some Operating Systems provide interfaces for all kinds of CPU and memory bindings, some others provide only interfaces for a limited number of kinds of CPU and memory binding, and some do not provide any binding interface at all. Hwloc's binding functions would then simply return the ENOSYS error (Function not implemented), meaning that the underlying Operating System does not provide any interface for them. CPU binding and Memory binding provide more information on which hwloc binding functions should be preferred because interfaces for them are usually available on the supported Operating Systems.

-

Similarly, the ability of reporting topology information varies from one platform to another. As shown in Command-line Examples, hwloc can obtain information on a wide variety of hardware topologies. However, some platforms and/or operating system versions will only report a subset of this information. For example, on an PPC64-based system with 8 cores (each with 2 hardware threads) running a default 2.6.18-based kernel from RHEL 5.4, hwloc is only able to glean information about NUMA nodes and processor units (PUs). No information about caches, packages, or cores is available.

-

Here's the graphical output from lstopo on this platform when Simultaneous Multi-Threading (SMT) is enabled:

-
- -
-

And here's the graphical output from lstopo on this platform when SMT is disabled:

-
- -
-

Notice that hwloc only sees half the PUs when SMT is disabled. PU L#6, for example, seems to change location from NUMA node #0 to #1. In reality, no PUs "moved" – they were simply re-numbered when hwloc only saw half as many (see also Logical index in Indexes and Sets). Hence, PU L#6 in the SMT-disabled picture probably corresponds to PU L#12 in the SMT-enabled picture.

-

This same "PUs have disappeared" effect can be seen on other platforms – even platforms / OSs that provide much more information than the above PPC64 system. This is an unfortunate side-effect of how operating systems report information to hwloc.

-

Note that upgrading the Linux kernel on the same PPC64 system mentioned above to 2.6.34, hwloc is able to discover all the topology information. The following picture shows the entire topology layout when SMT is enabled:

-
- -
-

Developers using the hwloc API or XML output for portable applications should therefore be extremely careful to not make any assumptions about the structure of data that is returned. For example, per the above reported PPC topology, it is not safe to assume that PUs will always be descendants of cores.

-

Additionally, future hardware may insert new topology elements that are not available in this version of hwloc. Long-lived applications that are meant to span multiple different hardware platforms should also be careful about making structure assumptions. For example, a new element may someday exist between a core and a PU.

-

-API Example

-

The following small C example (available in the source tree as ``doc/examples/hwloc-hello.c'') prints the topology of the machine and performs some thread and memory binding. More examples are available in the doc/examples/ directory of the source tree.

-
/* Example hwloc API program.
-
*
-
* See other examples under doc/examples/ in the source tree
-
* for more details.
-
*
-
* Copyright © 2009-2016 Inria. All rights reserved.
-
* Copyright © 2009-2011 Université Bordeaux
-
* Copyright © 2009-2010 Cisco Systems, Inc. All rights reserved.
-
* See COPYING in top-level directory.
-
*
-
* hwloc-hello.c
-
*/
-
-
#include "hwloc.h"
-
-
#include <errno.h>
-
#include <stdio.h>
-
#include <string.h>
-
-
static void print_children(hwloc_topology_t topology, hwloc_obj_t obj,
-
int depth)
-
{
-
char type[32], attr[1024];
-
unsigned i;
-
-
hwloc_obj_type_snprintf(type, sizeof(type), obj, 0);
-
printf("%*s%s", 2*depth, "", type);
-
if (obj->os_index != (unsigned) -1)
-
printf("#%u", obj->os_index);
-
hwloc_obj_attr_snprintf(attr, sizeof(attr), obj, " ", 0);
-
if (*attr)
-
printf("(%s)", attr);
-
printf("\n");
-
for (i = 0; i < obj->arity; i++) {
-
print_children(topology, obj->children[i], depth + 1);
-
}
-
}
-
-
int main(void)
-
{
-
int depth;
-
unsigned i, n;
-
unsigned long size;
-
int levels;
-
char string[128];
-
int topodepth;
-
void *m;
-
hwloc_topology_t topology;
-
hwloc_cpuset_t cpuset;
-
hwloc_obj_t obj;
-
-
/* Allocate and initialize topology object. */
-
hwloc_topology_init(&topology);
-
-
/* ... Optionally, put detection configuration here to ignore
-
some objects types, define a synthetic topology, etc....
-
-
The default is to detect all the objects of the machine that
-
the caller is allowed to access. See Configure Topology
-
Detection. */
-
-
/* Perform the topology detection. */
-
hwloc_topology_load(topology);
-
-
/* Optionally, get some additional topology information
-
in case we need the topology depth later. */
-
topodepth = hwloc_topology_get_depth(topology);
-
-
/*****************************************************************
-
* First example:
-
* Walk the topology with an array style, from level 0 (always
-
* the system level) to the lowest level (always the proc level).
-
*****************************************************************/
-
for (depth = 0; depth < topodepth; depth++) {
-
printf("*** Objects at level %d\n", depth);
-
for (i = 0; i < hwloc_get_nbobjs_by_depth(topology, depth);
-
i++) {
-
hwloc_obj_type_snprintf(string, sizeof(string),
-
hwloc_get_obj_by_depth(topology, depth, i), 0);
-
printf("Index %u: %s\n", i, string);
-
}
-
}
-
-
/*****************************************************************
-
* Second example:
-
* Walk the topology with a tree style.
-
*****************************************************************/
-
printf("*** Printing overall tree\n");
-
print_children(topology, hwloc_get_root_obj(topology), 0);
-
-
/*****************************************************************
-
* Third example:
-
* Print the number of packages.
-
*****************************************************************/
-
depth = hwloc_get_type_depth(topology, HWLOC_OBJ_PACKAGE);
-
if (depth == HWLOC_TYPE_DEPTH_UNKNOWN) {
-
printf("*** The number of packages is unknown\n");
-
} else {
-
printf("*** %u package(s)\n",
-
hwloc_get_nbobjs_by_depth(topology, depth));
-
}
-
-
/*****************************************************************
-
* Fourth example:
-
* Compute the amount of cache that the first logical processor
-
* has above it.
-
*****************************************************************/
-
levels = 0;
-
size = 0;
-
for (obj = hwloc_get_obj_by_type(topology, HWLOC_OBJ_PU, 0);
-
obj;
-
obj = obj->parent)
-
if (hwloc_obj_type_is_cache(obj->type)) {
-
levels++;
-
size += obj->attr->cache.size;
-
}
-
printf("*** Logical processor 0 has %d caches totaling %luKB\n",
-
levels, size / 1024);
-
-
/*****************************************************************
-
* Fifth example:
-
* Bind to only one thread of the last core of the machine.
-
*
-
* First find out where cores are, or else smaller sets of CPUs if
-
* the OS doesn't have the notion of a "core".
-
*****************************************************************/
-
depth = hwloc_get_type_or_below_depth(topology, HWLOC_OBJ_CORE);
-
-
/* Get last core. */
-
obj = hwloc_get_obj_by_depth(topology, depth,
-
hwloc_get_nbobjs_by_depth(topology, depth) - 1);
-
if (obj) {
-
/* Get a copy of its cpuset that we may modify. */
-
cpuset = hwloc_bitmap_dup(obj->cpuset);
-
-
/* Get only one logical processor (in case the core is
-
SMT/hyper-threaded). */
-
hwloc_bitmap_singlify(cpuset);
-
-
/* And try to bind ourself there. */
-
if (hwloc_set_cpubind(topology, cpuset, 0)) {
-
char *str;
-
int error = errno;
-
hwloc_bitmap_asprintf(&str, obj->cpuset);
-
printf("Couldn't bind to cpuset %s: %s\n", str, strerror(error));
-
free(str);
-
}
-
-
/* Free our cpuset copy */
-
hwloc_bitmap_free(cpuset);
-
}
-
-
/*****************************************************************
-
* Sixth example:
-
* Allocate some memory on the last NUMA node, bind some existing
-
* memory to the last NUMA node.
-
*****************************************************************/
-
/* Get last node. There's always at least one. */
-
n = hwloc_get_nbobjs_by_type(topology, HWLOC_OBJ_NUMANODE);
-
obj = hwloc_get_obj_by_type(topology, HWLOC_OBJ_NUMANODE, n - 1);
-
-
size = 1024*1024;
-
m = hwloc_alloc_membind(topology, size, obj->nodeset,
-
HWLOC_MEMBIND_BIND, HWLOC_MEMBIND_BYNODESET);
-
hwloc_free(topology, m, size);
-
-
m = malloc(size);
-
hwloc_set_area_membind(topology, m, size, obj->nodeset,
-
HWLOC_MEMBIND_BIND, HWLOC_MEMBIND_BYNODESET);
-
free(m);
-
-
/* Destroy topology object. */
-
hwloc_topology_destroy(topology);
-
-
return 0;
-
}
-
hwloc_cpuset_t
hwloc_bitmap_t hwloc_cpuset_t
A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
Definition: hwloc.h:140
-
HWLOC_OBJ_NUMANODE
@ HWLOC_OBJ_NUMANODE
NUMA node. An object that contains memory that is directly and byte-accessible to the host processors...
Definition: hwloc.h:236
-
HWLOC_OBJ_PACKAGE
@ HWLOC_OBJ_PACKAGE
Physical package. The physical package that usually gets inserted into a socket on the motherboard....
Definition: hwloc.h:191
-
HWLOC_OBJ_PU
@ HWLOC_OBJ_PU
Processing Unit, or (Logical) Processor. An execution unit (may share a core with some other logical ...
Definition: hwloc.h:201
-
HWLOC_OBJ_CORE
@ HWLOC_OBJ_CORE
Core. A computation unit (may be shared by several PUs, aka logical processors).
Definition: hwloc.h:197
-
hwloc_topology_init
int hwloc_topology_init(hwloc_topology_t *topologyp)
Allocate a topology context.
-
hwloc_topology_t
struct hwloc_topology * hwloc_topology_t
Topology context.
Definition: hwloc.h:692
-
hwloc_topology_destroy
void hwloc_topology_destroy(hwloc_topology_t topology)
Terminate and free a topology context.
-
hwloc_topology_load
int hwloc_topology_load(hwloc_topology_t topology)
Build the actual topology.
-
hwloc_get_nbobjs_by_depth
unsigned hwloc_get_nbobjs_by_depth(hwloc_topology_t topology, int depth)
Returns the width of level at depth depth.
-
hwloc_get_root_obj
static hwloc_obj_t hwloc_get_root_obj(hwloc_topology_t topology)
Returns the top-object of the topology-tree.
-
hwloc_get_obj_by_depth
hwloc_obj_t hwloc_get_obj_by_depth(hwloc_topology_t topology, int depth, unsigned idx)
Returns the topology object at logical index idx from depth depth.
-
hwloc_get_obj_by_type
static hwloc_obj_t hwloc_get_obj_by_type(hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx)
Returns the topology object at logical index idx with type type.
-
hwloc_get_nbobjs_by_type
static int hwloc_get_nbobjs_by_type(hwloc_topology_t topology, hwloc_obj_type_t type)
Returns the width of level type type.
-
hwloc_get_type_or_below_depth
static int hwloc_get_type_or_below_depth(hwloc_topology_t topology, hwloc_obj_type_t type)
Returns the depth of objects of type type or below.
-
hwloc_get_type_depth
int hwloc_get_type_depth(hwloc_topology_t topology, hwloc_obj_type_t type)
Returns the depth of objects of type type.
-
hwloc_topology_get_depth
int hwloc_topology_get_depth(hwloc_topology_t restrict topology)
Get the depth of the hierarchical tree of objects.
-
HWLOC_TYPE_DEPTH_UNKNOWN
@ HWLOC_TYPE_DEPTH_UNKNOWN
No object of given type exists in the topology.
Definition: hwloc.h:822
-
hwloc_obj_attr_snprintf
int hwloc_obj_attr_snprintf(char *restrict string, size_t size, hwloc_obj_t obj, const char *restrict separator, int verbose)
Stringify the attributes of a given topology object into a human-readable form.
-
hwloc_obj_type_snprintf
int hwloc_obj_type_snprintf(char *restrict string, size_t size, hwloc_obj_t obj, int verbose)
Stringify the type of a given topology object into a human-readable form.
-
hwloc_set_cpubind
int hwloc_set_cpubind(hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags)
Bind current process or thread on CPUs given in physical bitmap set.
-
hwloc_alloc_membind
void * hwloc_alloc_membind(hwloc_topology_t topology, size_t len, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags)
Allocate some memory on NUMA memory nodes specified by set.
-
hwloc_free
int hwloc_free(hwloc_topology_t topology, void *addr, size_t len)
Free memory that was previously allocated by hwloc_alloc() or hwloc_alloc_membind().
-
hwloc_set_area_membind
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)
Bind the already-allocated memory identified by (addr, len) to the NUMA node(s) specified by set.
-
HWLOC_MEMBIND_BYNODESET
@ HWLOC_MEMBIND_BYNODESET
Consider the bitmap argument as a nodeset.
Definition: hwloc.h:1509
-
HWLOC_MEMBIND_BIND
@ HWLOC_MEMBIND_BIND
Allocate memory on the specified nodes.
Definition: hwloc.h:1421
-
hwloc_obj_type_is_cache
int hwloc_obj_type_is_cache(hwloc_obj_type_t type)
Check whether an object type is a CPU Cache (Data, Unified or Instruction).
-
hwloc_bitmap_asprintf
int hwloc_bitmap_asprintf(char **strp, hwloc_const_bitmap_t bitmap)
Stringify a bitmap into a newly allocated string.
-
hwloc_bitmap_free
void hwloc_bitmap_free(hwloc_bitmap_t bitmap)
Free bitmap bitmap.
-
hwloc_bitmap_singlify
int hwloc_bitmap_singlify(hwloc_bitmap_t bitmap)
Keep a single index among those set in bitmap bitmap.
-
hwloc_bitmap_dup
hwloc_bitmap_t hwloc_bitmap_dup(hwloc_const_bitmap_t bitmap)
Duplicate bitmap bitmap by allocating a new bitmap and copying bitmap contents.
-
hwloc_obj
Structure of a topology object.
Definition: hwloc.h:396
-
hwloc_obj::children
struct hwloc_obj ** children
Normal children, children[0 .. arity -1].
Definition: hwloc.h:456
-
hwloc_obj::nodeset
hwloc_nodeset_t nodeset
NUMA nodes covered by this object or containing this object.
Definition: hwloc.h:540
-
hwloc_obj::os_index
unsigned os_index
OS-provided physical index number. It is not guaranteed unique across the entire machine,...
Definition: hwloc.h:401
-
hwloc_obj::cpuset
hwloc_cpuset_t cpuset
CPUs covered by this object.
Definition: hwloc.h:512
-
hwloc_obj::arity
unsigned arity
Number of normal children. Memory, Misc and I/O children are not listed here but rather in their dedi...
Definition: hwloc.h:452
-
hwloc_obj::type
hwloc_obj_type_t type
Type of object.
Definition: hwloc.h:398
-
hwloc_obj::attr
union hwloc_obj_attr_u * attr
Object type-specific Attributes, may be NULL if no attribute value was found.
Definition: hwloc.h:415
-
hwloc_obj::parent
struct hwloc_obj * parent
Parent, NULL if root (Machine object)
Definition: hwloc.h:446
-
hwloc_obj_attr_u::cache
struct hwloc_obj_attr_u::hwloc_cache_attr_s cache
-
hwloc_obj_attr_u::hwloc_cache_attr_s::size
hwloc_uint64_t size
Size of cache in bytes.
Definition: hwloc.h:617
-

hwloc provides a pkg-config executable to obtain relevant compiler and linker flags. For example, it can be used thusly to compile applications that utilize the hwloc library (assuming GNU Make):

-
CFLAGS += $(shell pkg-config --cflags hwloc)
-LDLIBS += $(shell pkg-config --libs hwloc)
-
-hwloc-hello: hwloc-hello.c
-        $(CC) hwloc-hello.c $(CFLAGS) -o hwloc-hello $(LDLIBS)
-

On a machine 2 processor packages – each package of which has two processing cores – the output from running hwloc-hello could be something like the following:

-
shell$ ./hwloc-hello
-*** Objects at level 0
-Index 0: Machine
-*** Objects at level 1
-Index 0: Package#0
-Index 1: Package#1
-*** Objects at level 2
-Index 0: Core#0
-Index 1: Core#1
-Index 2: Core#3
-Index 3: Core#2
-*** Objects at level 3
-Index 0: PU#0
-Index 1: PU#1
-Index 2: PU#2
-Index 3: PU#3
-*** Printing overall tree
-Machine
-  Package#0
-    Core#0
-      PU#0
-    Core#1
-      PU#1
-  Package#1
-    Core#3
-      PU#2
-    Core#2
-      PU#3
-*** 2 package(s)
-*** Logical processor 0 has 0 caches totaling 0KB
-shell$ 
-

-

-

-

-History / Credits

-

hwloc is the evolution and merger of the libtopology project and the Portable Linux Processor Affinity (PLPA) (https://www.open-mpi.org/projects/plpa/) project. Because of functional and ideological overlap, these two code bases and ideas were merged and released under the name "hwloc" as an Open MPI sub-project.

-

libtopology was initially developed by the Inria Runtime Team-Project. PLPA was initially developed by the Open MPI development team as a sub-project. Both are now deprecated in favor of hwloc, which is distributed as an Open MPI sub-project.

-

-

-

-
-
- - - - - - - -
-
-
Terms and Definitions
-
-
-

-

-

-

-Objects

-
-
Object
-

Interesting kind of part of the system, such as a Core, a L2Cache, a NUMA memory node, etc. The different types detected by hwloc are detailed in the hwloc_obj_type_t enumeration.

-

There are four kinds of Objects: Memory (NUMA nodes and Memory-side caches), I/O (Bridges, PCI and OS devices), Misc, and Normal (everything else, including Machine, Package, Die, Core, PU, CPU Caches, etc.). Normal and Memory objects have (non-NULL) CPU sets and nodesets, while I/O and Misc don't.

-

Objects are topologically sorted by locality (CPU and node sets) into a tree (see Hierarchy, Tree and Levels).

-

-
-
Processing Unit (PU)
-

The smallest processing element that can be represented by a hwloc object. It may be a single-core processor, a core of a multicore processor, or a single thread in a SMT processor (also sometimes called "Logical processor", not to be confused with "Logical index of a processor"). hwloc's PU acronym stands for Processing Unit.

-

-
-
Package
-

A processor Package is the physical package that usually gets inserted into a socket on the motherboard. It is also often called a physical processor or a CPU even if these names bring confusion with respect to cores and processing units. A processor package usually contains multiple cores (and may also be composed of multiple dies). hwloc Package objects were called Sockets up to hwloc 1.10.

-

-
-
NUMA Node
-

An object that contains memory that is directly and byte-accessible to the host processors. It is usually close to some cores as specified by its CPU set. Hence it is attached as a memory child of the object that groups those cores together, for instance a Package objects with 4 Core children (see Hierarchy, Tree and Levels).

-

-
-
Memory-side Cache
-

A cache in front of a specific memory region (e.g. a range of physical addresses). It caches all accesses to that region without caring about which core issued the request. This is the opposite of usual CPU caches where only accesses from the local cores are cached, without caring about the target memory.

-

In hwloc, memory-side caches are memory objects placed between their local CPU objects (parent) and the target NUMA node memory (child).

-
-
-

-

-

-

-Indexes and Sets

-
-
OS or physical index
-

The index that the operating system (OS) uses to identify the object. This may be completely arbitrary, non-unique, non-contiguous, not representative of logical proximity, and may depend on the BIOS configuration. That is why hwloc almost never uses them, only in the default lstopo output (P#x) and cpuset masks. See also Should I use logical or physical/OS indexes? and how?.

-

-
-
Logical index
-

Index to uniquely identify objects of the same type and depth, automatically computed by hwloc according to the topology. It expresses logical proximity in a generic way, i.e. objects which have adjacent logical indexes are adjacent in the topology. That is why hwloc almost always uses it in its API, since it expresses logical proximity. They can be shown (as L#x) by lstopo thanks to the -l option. This index is always linear and in the range [0, num_objs_same_type_same_level-1]. Think of it as ``cousin rank.'' The ordering is based on topology first, and then on OS CPU numbers, so it is stable across everything except firmware CPU renumbering. "Logical index" should not be confused with "Logical processor". A "Logical - processor" (which in hwloc we rather call "processing unit" to avoid the confusion) has both a physical index (as chosen arbitrarily by BIOS/OS) and a logical index (as computed according to logical proximity by hwloc). See also Should I use logical or physical/OS indexes? and how?.

-

-
-
CPU set
-

The set of processing units (PU) logically included in an object (if it makes sense). They are always expressed using physical processor numbers (as announced by the OS). They are implemented as the hwloc_bitmap_t opaque structure. hwloc CPU sets are just masks, they do not have any relation with an operating system actual binding notion like Linux' cpusets. I/O and Misc objects do not have CPU sets while all Normal and Memory objects have non-NULL CPU sets.

-

-
-
Node set
-

The set of NUMA memory nodes logically included in an object (if it makes sense). They are always expressed using physical node numbers (as announced by the OS). They are implemented with the hwloc_bitmap_t opaque structure. as bitmaps. I/O and Misc objects do not have Node sets while all Normal and Memory objects have non-NULL nodesets.

-

-
-
Bitmap
-

A possibly-infinite set of bits used for describing sets of objects such as CPUs (CPU sets) or memory nodes (Node sets). They are implemented with the hwloc_bitmap_t opaque structure.

-

-
-
-

-

-

-

-Hierarchy, Tree and Levels

-
-
Parent object
-

The object logically containing the current object, for example because its CPU set includes the CPU set of the current object. All objects have a non-NULL parent, except the root of the topology (Machine object).

-

-
-
Ancestor object
-

The parent object, or its own parent, and so on.

-

-
-
Children object(s)
-

The object (or objects) contained in the current object because their CPU set is included in the CPU set of the current object. Each object may also contain separated lists for Memory, I/O and Misc object children.

-

-
-
Arity
-

The number of normal children of an object. There are also specific arities for Memory, I/O and Misc children.

-

-
-
Sibling objects
-

Objects in the same children list, which all of them are normal children of the same parent, or all of them are Memory children of the same parent, or I/O children, or Misc. They usually have the same type (and hence are cousins, as well). But they may not if the topology is asymmetric.

-

-
-
Sibling rank
-

Index to uniquely identify objects which have the same parent, and is always in the range [0, arity-1] (respectively memory_arity, io_arity or misc_arity for Memory, I/O and Misc children of a parent).

-

-
-
Cousin objects
-

Objects of the same type (and depth) as the current object, even if they do not have the same parent.

-

-
-
Level
-

Set of objects of the same type and depth. All these objects are cousins.

-

Memory, I/O and Misc objects also have their own specific levels and (virtual) depth.

-

-
-
Depth
-

Nesting level in the object tree, starting from the root object. If the topology is symmetric, the depth of a child is equal to the parent depth plus one, and an object depth is also equal to the number of parent/child links between the root object and the given object. If the topology is asymmetric, the difference between some parent and child depths may be larger than one when some intermediate levels (for instance groups) are missing in only some parts of the machine.

-

The depth of the Machine object is always 0 since it is always the root of the topology. The depth of PU objects is equal to the number of levels in the topology minus one.

-

Memory, I/O and Misc objects also have their own specific levels and depth.

-

-
-
-

The following diagram can help to understand the vocabulary of the relationships by showing the example of a machine with two dual core packages (with no hardware threads); thus, a topology with 5 levels. Each box with rounded corner corresponds to one hwloc_obj_t, containing the values of the different integer fields (depth, logical_index, etc.), and arrows show to which other hwloc_obj_t pointers point to (first_child, parent, etc.).

-

The topology always starts with a Machine object as root (depth 0) and ends with PU objects at the bottom (depth 4 here).

-

Objects of the same level (cousins) are listed in red boxes and linked with red arrows. Children of the same parent (siblings) are linked with blue arrows.

-

The L2 cache of the last core is intentionally missing to show how asymmetric topologies are handled. See What happens if my topology is asymmetric? for more information about such strange topologies.

-
- -
-

It should be noted that for PU objects, the logical index – as computed linearly by hwloc – is not the same as the OS index.

-

The NUMA node is on the side because it is not part of the main tree but rather attached to the object that corresponds to its locality (the entire machine here, hence the root object). It is attached as a Memory child (in green) and has a virtual depth (negative). It could also have siblings if there were multiple local NUMA nodes, or cousins if other NUMA nodes were attached somewhere else in the machine.

-

I/O or Misc objects could be attached in a similar manner.

-
-
- - - - - - -
-
-
-
Command-Line Tools
-
-
-

-

-

-

hwloc comes with an extensive C programming interface and several command line utilities. Each of them is fully documented in its own manual page; the following is a summary of the available command line tools.

-

-

-

-

-lstopo and lstopo-no-graphics

-

lstopo (also known as hwloc-ls) displays the hierarchical topology map of the current system. The output may be graphical, ascii-art or textual, and can also be exported to numerous file formats such as PDF, PNG, XML, and others. Advanced graphical outputs require the "Cairo" development package (usually cairo-devel or libcairo2-dev).

-

lstopo and lstopo-no-graphics accept the same command-line options. However, graphical outputs are only available in lstopo. Textual outputs (those that do not depend on heavy external libraries such as Cairo) are supported in both lstopo and lstopo-no-graphics.

-

This command can also display the processes currently bound to a part of the machine (via the --ps option).

-

Note that lstopo can read XML files and/or alternate chroot filesystems and display topological maps representing those systems (e.g., use lstopo to output an XML file on one system, and then use lstopo to read in that XML file and display it on a different system).

-

-

-

-

-hwloc-bind

-

hwloc-bind binds processes to specific hardware objects through a flexible syntax. A simple example is binding an executable to specific cores (or packages or bitmaps or ...). The hwloc-bind(1) man page provides much more detail on what is possible.

-

hwloc-bind can also be used to retrieve the current process' binding, or retrieve the last CPU(s) where a process ran, or operate on memory binding.

-

Just like hwloc-calc, the input locations given to hwloc-bind may be either objects or cpusets (bitmaps as reported by hwloc-calc or hwloc-distrib).

-

-

-

-

-hwloc-calc

-

hwloc-calc is hwloc's Swiss Army Knife command-line tool for converting things. The input may be either objects or cpusets (bitmaps as reported by another hwloc-calc instance or by hwloc-distrib), that may be combined by addition, intersection or subtraction. The output may be expressed as:

    -
  • -a cpuset bitmap: This compact opaque representation of objects is useful for shell scripts etc. It may passed to hwloc command-line tools such as hwloc-calc or hwloc-bind, or to hwloc command-line options such as lstopo --restrict.
    • -
  • -a nodeset bitmap: Another opaque representation that represents memory locality more precisely, especially if some NUMA nodes are CPU less or if multiple NUMA nodes are local to the same CPUs.
    • -
  • -the amount of the equivalent hwloc objects from a specific type, or the list of their indexes. This is useful for iterating over all similar objects (for instance all cores) within a given part of a platform.
    • -
  • -a hierarchical description of objects, for instance a thread index within a core within a package. This gives a better view of the actual location of an object.
    • -
-

Moreover, input and/or output may be use either physical/OS object indexes or as hwloc's logical object indexes. It eases cooperation with external tools such as taskset or numactl by exporting hwloc specifications into list of processor or NUMA node physical indexes. See also Should I use logical or physical/OS indexes? and how?.

-

-

-

-

-hwloc-info

-

hwloc-info dumps information about the given objects, as well as all its specific attributes. It is intended to be used with tools such as grep for filtering certain attribute lines. When no object is specified, or when --topology is passed, hwloc-info prints a summary of the topology. When --support is passed, hwloc-info lists the supported features for the topology.

-

-

-

-

-hwloc-distrib

-

hwloc-distrib generates a set of cpuset bitmaps that are uniformly distributed across the machine for the given number of processes. These strings may be used with hwloc-bind to run processes to maximize their memory bandwidth by properly distributing them across the machine.

-

-

-

-

-hwloc-ps

-

hwloc-ps is a tool to display the bindings of processes that are currently running on the local machine. By default, hwloc-ps only lists processes that are bound; unbound process (and Linux kernel threads) are not displayed.

-

-

-

-

-hwloc-annotate

-

hwloc-annotate may modify object (and topology) attributes such as string information (see Custom string infos for details) or Misc children objects. It may also add distances, memory attributes, etc. to the topology. It reads an input topology from a XML file and outputs the annotated topology as another XML file.

-

-

-

-

-hwloc-diff, hwloc-patch and hwloc-compress-dir

-

hwloc-diff computes the difference between two topologies and outputs it to another XML file.

-

hwloc-patch reads such a difference file and applies to another topology.

-

hwloc-compress-dir compresses an entire directory of XML files by using hwloc-diff to save the differences between topologies instead of entire topologies.

-

-

-

-

-hwloc-dump-hwdata

-

hwloc-dump-hwdata is a Linux and x86-specific tool that dumps (during boot, privileged) some topology and locality information from raw hardware files (SMBIOS and ACPI tables) to human-readable and world-accessible files that the hwloc library will later reuse.

-

Currently only used on Intel Xeon Phi processor platforms. See Why do I need hwloc-dump-hwdata for memory on Intel Xeon Phi processor?.

-

See HWLOC_DUMPED_HWDATA_DIR in Environment Variables for details about the location of dumped files.

-

-

-

-

-hwloc-gather-topology and hwloc-gather-cpuid

-

hwloc-gather-topology is a Linux-specific tool that saves the relevant topology files of the current machine into a tarball (and the corresponding lstopo outputs).

-

hwloc-gather-cpuid is a x86-specific tool that dumps the result of CPUID instructions on the current machine into a directory.

-

The output of hwloc-gather-cpuid is included in the tarball saved by hwloc-gather-topology when running on Linux/x86.

-

These files may be used later (possibly offline) for simulating or debugging a machine without actually running on it.

-
-
- - - - - - -
-
-
-
Environment Variables
-
-
-

-

-

-

The behavior of the hwloc library and tools may be tuned thanks to the following environment variables.

-
-
HWLOC_XMLFILE=/path/to/file.xml
-

enforces the discovery from the given XML file as if hwloc_topology_set_xml() had been called. This file may have been generated earlier with lstopo file.xml. For convenience, this backend provides empty binding hooks which just return success. To have hwloc still actually call OS-specific hooks, HWLOC_THISSYSTEM should be set 1 in the environment too, to assert that the loaded file is really the underlying system. See also Importing and exporting topologies from/to XML files.

-

-
-
HWLOC_SYNTHETIC=synthetic_description
-

enforces the discovery through a synthetic description string as if hwloc_topology_set_synthetic() had been called. For convenience, this backend provides empty binding hooks which just return success. See also Synthetic topologies.

-

-
-
HWLOC_XML_VERBOSE=1
-
-
HWLOC_SYNTHETIC_VERBOSE=1
-

enables verbose messages in the XML or synthetic topology backends. hwloc XML backends (see Importing and exporting topologies from/to XML files) can emit some error messages to the error output stream. Enabling these verbose messages within hwloc can be useful for understanding failures to parse input XML topologies. Similarly, enabling verbose messages in the synthetic topology backend can help understand why the description string is invalid. See also Synthetic topologies.

-

-
-
HWLOC_THISSYSTEM=1
-

enforces the return value of hwloc_topology_is_thissystem(), as if HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM was set with hwloc_topology_set_flags(). It means that it makes hwloc assume that the selected backend provides the topology for the system on which we are running, even if it is not the OS-specific backend but the XML backend for instance. This means making the binding functions actually call the OS-specific system calls and really do binding, while the XML backend would otherwise provide empty hooks just returning success. This can be used for efficiency reasons to first detect the topology once, save it to a XML file, and quickly reload it later through the XML backend, but still having binding functions actually do bind. This also enables support for the variable HWLOC_THISSYSTEM_ALLOWED_RESOURCES.

-

-
-
HWLOC_THISSYSTEM_ALLOWED_RESOURCES=1
-

Get the set of allowed resources from the native operating system even if the topology was loaded from XML or synthetic description, as if HWLOC_TOPOLOGY_FLAG_THISSYSTEM_ALLOWED_RESOURCES was set with hwloc_topology_set_flags(). This variable requires the topology to match the current system (see the variable HWLOC_THISSYSTEM). This is useful when the topology is not loaded directly from the local machine (e.g. for performance reason) and it comes with all resources, but the running process is restricted to only a part of the machine (for instance because of Linux Cgroup/Cpuset).

-

-
-
HWLOC_ALLOW=all
-

Totally ignore administrative restrictions such as Linux Cgroups and consider all resources (PUs and NUMA nodes) as allowed. This is different from setting HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED which gathers all resources but marks the unavailable ones as disallowed.

-

-
-
HWLOC_HIDE_ERRORS=1
-

enables or disables verbose reporting of errors. The hwloc library may issue warnings to the standard error stream when it detects a problem during topology discovery, for instance if the operating system (or user) gives contradictory topology information.

-

By default (1), hwloc only shows critical errors such as invalid hardware topology information or invalid configuration. If set to 0 (default in lstopo), more errors are displayed, for instance a failure to initialize CUDA or NVML. If set to 2, no hwloc error messages are shown.

-

Note that additional verbose messages may be enabled with other variables such as HWLOC_GROUPING_VERBOSE.

-

-
-
HWLOC_USE_NUMA_DISTANCES=7
-

enables or disables the use of NUMA distances. NUMA distances and memory target/initiator information may be used to improve the locality of NUMA nodes, especially CPU-less nodes. Bits in the value of this environment variable enable different features: Bit 0 enables the gathering of NUMA distances from the operating system. Bit 1 further enables the use of NUMA distances to improve the locality of CPU-less nodes. Bit 2 enables the use of target/initiator information.

-

-
-
HWLOC_GROUPING=1
-

enables or disables objects grouping based on distances. By default, hwloc uses distance matrices between objects (either read from the OS or given by the user) to find groups of close objects. These groups are described by adding intermediate Group objects in the topology. Setting this environment variable to 0 will disable this grouping. This variable supersedes the obsolete HWLOC_IGNORE_DISTANCES variable.

-

-
-
HWLOC_GROUPING_ACCURACY=0.05
-

relaxes distance comparison during grouping. By default, objects may be grouped if their distances form a minimal distance graph. When setting this variable to 0.02, and when HWLOC_DISTANCES_ADD_FLAG_GROUP_INACCURATE is given, these distances do not have to be strictly equal anymore, they may just be equal with a 2% error. If set to try instead of a numerical value, hwloc will try to group with perfect accuracy (0, the default), then with 0.01, 0.02, 0.05 and finally 0.1. Numbers given in this environment variable should always use a dot as a decimal mark (for instance 0.01 instead of 0,01).

-

-
-
HWLOC_GROUPING_VERBOSE=0
-

enables or disables some verbose messages during grouping. If this variable is set to 1, some debug messages will be displayed during distance-based grouping of objects even if debug was not specific at configure time. This is useful when trying to find an interesting distance grouping accuracy.

-

-
-
HWLOC_CPUKINDS_RANKING=default
-

change the ranking policy for CPU kinds. hwloc tries to rank CPU kinds that are energy efficiency first, and then CPUs that are rather high-performance and power hungry.
- By default, if available, the OS-provided efficiency is used for ranking. Otherwise, the frequency and/or core types are used when available.
- This environment variable may be set to coretype+frequency, coretype+frequency_strict, coretype, frequency, frequency_base, frequency_max, forced_efficiency, no_forced_efficiency, default, or none.

-

-
-
HWLOC_CPUKINDS_MAXFREQ=adjust=10
-

change the use of the max frequency in the Linux backend. hwloc tries to read the base and max frequencies of each core on Linux. Some hardware features such as Intel Turbo Boost Max 3.0 make some cores report slightly higher max frequencies than others in the same CPU package. Despite having slightly different frequencies, these cores are considered identical instead of exposing an hybrid CPU. Hence, by default, hwloc uniformizes the max frequencies of cores that have the same base frequency (higher values are downgraded by up to 10%).

-

If this environment variable is set to adjust=X, the 10% threshold is replaced with X. If set to 1, max frequencies are not adjusted anymore, some homogeneous processors may appear hybrid because of this. If set to 0, max frequencies are entirely ignored.

-

-
-
HWLOC_PCI_LOCALITY=<domain/bus> <cpuset>;...
-
-
HWLOC_PCI_LOCALITY=/path/to/pci/locality/file
-

changes the locality of I/O devices behing the specified PCI buses. If no I/O locality information is available or if the BIOS reports incorrect information, it is possible to move a I/O device tree (OS and/or PCI devices with optional bridges) near a custom set of processors.
- Localities are given either inside the environment variable itself, or in the pointed file. They may be separated either by semi-colons or by line-breaks. Invalid localities are silently ignored, hence it is possible to insert comments between actual localities.
- Each locality contains a domain/bus specification (in hexadecimal numbers as usual) followed by a whitespace and a cpuset:

    -
  • -0001 <cpuset> specifies the locality of all buses in PCI domain 0000.
    • -
  • -0000:0f <cpuset> specifies only PCI bus 0f in domain 0000.
    • -
  • -0002:04-0a <cpuset> specifies a range of buses (from 04 to 0a) within domain 0002.
    • -
-

Domain/bus specifications should usually match entire hierarchies of buses behind a bridge (including primary, secondary and subordinate buses). For instance, if hostbridge 0000:00 is above other bridges/switches with buses 0000:01 to 0000:09, the variable should be HWLOC_PCI_LOCALITY="0000:00-09 <cpuset>". It supersedes the old HWLOC_PCI_0000_00_LOCALCPUS=<cpuset> which only works when hostbridges exist in the topology.
- If the variable is defined to empty or invalid, no forced PCI locality is applied but hwloc's internal automatic locality quirks are disabled, which means the exact PCI locality reported by the platform is used.

-

-
-
HWLOC_X86_TOPOEXT_NUMANODES=0
-

use AMD topoext CPUID leaf in the x86 backend to detect NUMA nodes. When using the x86 backend, setting this variable to 1 enables the building of NUMA nodes from AMD processor CPUID instructions. However this strategy does not always reflect BIOS configuration such as NUMA interleaving. And node indexes may be different from those of the operating system. Hence this should only be used when OS backends are wrong and the user is sure that CPUID returns correct NUMA information.

-

-
-
HWLOC_KEEP_NVIDIA_GPU_NUMA_NODES=0
-

show or hide NUMA nodes that correspond to NVIDIA GPU memory. By default they are ignored to avoid interleaved memory being allocated on GPU by mistake. Setting this environment variable to 1 exposes these NUMA nodes. They may be recognized by the GPUMemory subtype. They also have a PCIBusID info attribute to identify the corresponding GPU.

-

-
-
HWLOC_KNL_MSCACHE_L3=0
-

Expose the KNL MCDRAM in cache mode as a Memory-side Cache instead of a L3. hwloc releases prior to 2.1 exposed the MCDRAM cache as a CPU-side L3 cache. Now that Memory-side caches are supported by hwloc, it is still exposed as a L3 by default to avoid breaking existing applications. Setting this environment variable to 1 will expose it as a proper Memory-side cache.

-

-
-
HWLOC_WINDOWS_PROCESSOR_GROUP_OBJS=0
-

Expose Windows processor groups as hwloc Group objects. By default, these groups are disabled because they may be incompatible with the hierarchy of resources that hwloc builds (leading to warnings). Setting this variable to 1 reenables the addition of these groups to the topology.

-

This variable does not impact the querying of Windows processor groups using the dedicated API in hwloc/windows.h, this feature is always supported.

-

-
-
HWLOC_ANNOTATE_GLOBAL_COMPONENTS=0
-

Allow components to annotate the topology even if they are usually excluded by global components by default. Setting this variable to 1 and also setting HWLOC_COMPONENTS=xml,pci,stop enables the addition of PCI vendor and model info attributes to a XML topology that was generated without those names (if pciaccess was missing).

-

-
-
HWLOC_FSROOT=/path/to/linux/filesystem-root/
-

switches to reading the topology from the specified Linux filesystem root instead of the main file-system root. This directory may have been saved previously from another machine with hwloc-gather-topology.
- One should likely also set HWLOC_COMPONENTS=linux,stop so that non-Linux backends are disabled (the -i option of command-line tools takes care of both).
- Not using the main file-system root causes hwloc_topology_is_thissystem() to return 0. For convenience, this backend provides empty binding hooks which just return success. To have hwloc still actually call OS-specific hooks, HWLOC_THISSYSTEM should be set 1 in the environment too, to assert that the loaded file is really the underlying system.

-

-
-
HWLOC_CPUID_PATH=/path/to/cpuid/
-

forces the x86 backend to read dumped CPUIDs from the given directory instead of executing actual x86 CPUID instructions. This directory may have been saved previously from another machine with hwloc-gather-cpuid.
- One should likely also set HWLOC_COMPONENTS=x86,stop so that non-x86 backends are disabled (the -i option of command-line tools takes care of both).
- It causes hwloc_topology_is_thissystem() to return 0. For convenience, this backend provides empty binding hooks which just return success. To have hwloc still actually call OS-specific hooks, HWLOC_THISSYSTEM should be set 1 in the environment too, to assert that the loaded CPUID dump is really the underlying system.

-

-
-
HWLOC_DUMPED_HWDATA_DIR=/path/to/dumped/files/
-

loads files dumped by hwloc-dump-hwdata (on Linux) from the given directory. The default dump/load directory is configured during build based on --runstatedir, --localstatedir, and --prefix options. It usually points to /var/run/hwloc/ in Linux distribution packages, but it may also point to $prefix/var/run/hwloc/ when manually installing and only specifying --prefix.

-

-
-
HWLOC_COMPONENTS=list,of,components
-

forces a list of components to enable or disable. Enable or disable the given comma-separated list of components (if they do not conflict with each other). Component names prefixed with - are disabled (a single phase may also be disabled).

-

Once the end of the list is reached, hwloc falls back to enabling the remaining components (sorted by priority) that do not conflict with the already enabled ones, and unless explicitly disabled in the list. If stop is met, the enabling loop immediately stops, no more component is enabled.

-

If xml or synthetic components are selected, the corresponding XML filename or synthetic description string should be pass in HWLOC_XMLFILE or HWLOC_SYNTHETIC respectively.

-

Since this variable is the low-level and more generic way to select components, it takes precedence over environment variables for selecting components.

-

If the variable is set to an empty string (or set to a single comma), no specific component is loaded first, all components are loaded in priority order.

-

See Selecting which components to use for details.

-

-
-
HWLOC_COMPONENTS_VERBOSE=1
-

displays verbose information about components. Display messages when components are registered or enabled. This is the recommended way to list the available components with their priority (all of them are registered at startup).

-

-
-
HWLOC_PLUGINS_PATH=/path/to/hwloc/plugins/:...
-

changes the default search directory for plugins. By default, $libdir/hwloc is used. The variable may contain several colon-separated directories.

-

-
-
HWLOC_PLUGINS_VERBOSE=1
-

displays verbose information about plugins. List which directories are scanned, which files are loaded, and which components are successfully loaded.

-

-
-
HWLOC_PLUGINS_BLACKLIST=filename1,filename2,...
-

prevents plugins from being loaded if their filename (without path) is listed. Plugin filenames may be found in verbose messages outputted when HWLOC_PLUGINS_VERBOSE=1.

-

-
-
HWLOC_DEBUG_VERBOSE=0
-

disables all verbose messages that are enabled by default when –enable-debug is passed to configure. When set to more than 1, even more verbose messages are displayed. The default is 1.

-

-
-
-
-
- - - - - - -
-
-
-
CPU and Memory Binding Overview
-
-
-

-

-

-

Some operating systems do not systematically provide separate functions for CPU and memory binding. This means that CPU binding functions may have have effects on the memory binding policy. Likewise, changing the memory binding policy may change the CPU binding of the current thread. This is often not a problem for applications, so by default hwloc will make use of these functions when they provide better binding support.

-

If the application does not want the CPU binding to change when changing the memory policy, it needs to use the HWLOC_MEMBIND_NOCPUBIND flag to prevent hwloc from using OS functions which would change the CPU binding. Additionally, HWLOC_CPUBIND_NOMEMBIND can be passed to CPU binding function to prevent hwloc from using OS functions would change the memory binding policy. Of course, using these flags will reduce hwloc's overall support for binding, so their use is discouraged.

-

One can avoid using these flags but still closely control both memory and CPU binding by allocating memory, touching each page in the allocated memory, and then changing the CPU binding. The already-really-allocated memory will then be "locked" to physical memory and will not be migrated. Thus, even if the memory binding policy gets changed by the CPU binding order, the already-allocated memory will not change with it. When binding and allocating further memory, the CPU binding should be performed again in case the memory binding altered the previously-selected CPU binding.

-

Not all operating systems support the notion of a "current" memory binding policy for the current process, but such operating systems often still provide a way to allocate data on a given node set. Conversely, some operating systems support the notion of a "current" memory binding policy and do not permit allocating data on a specific node set without changing the current policy and allocate the data. To provide the most powerful coverage of these facilities, hwloc provides:

-
    -
  • -functions that set/get the current memory binding policies (if supported): hwloc_set/get_membind() and hwloc_set/get_proc_membind()
    • -
  • -a function that allocates memory bound to specific node set without changing the current memory binding policy (if supported): hwloc_alloc_membind().
    • -
  • -a helper which, if needed, changes the current memory binding policy of the process in order to obtain memory binding: hwloc_alloc_membind_policy().
    • -
-

An application can thus use the two first sets of functions if it wants to manage separately the global process binding policy and directed allocation, or use the third set of functions if it does not care about the process memory binding policy.

-

See CPU binding and Memory binding for hwloc's API functions regarding CPU and memory binding, respectively. There are some examples under doc/examples/ in the source tree.

-
-
- - - - - - -
-
-
-
I/O Devices
-
-
-

-

-

-

hwloc usually manipulates processing units and memory but it can also discover I/O devices and report their locality as well. This is useful for placing I/O intensive applications on cores near the I/O devices they use, or for gathering information about all platform components.

-

-

-

-

-Enabling and requirements

-

I/O discovery is disabled by default (except in lstopo) for performance reasons. It can be enabled by changing the filtering of I/O object types to HWLOC_TYPE_FILTER_KEEP_IMPORTANT or HWLOC_TYPE_FILTER_KEEP_ALL before loading the topology, for instance with hwloc_topology_set_io_types_filter().

-

Note that I/O discovery requires significant help from the operating system. The pciaccess library (the development package is usually libpciaccess-devel or libpciaccess-dev) is needed to fully detect PCI devices and bridges/switches. On Linux, PCI discovery may still be performed even if libpciaccess cannot be used. But it misses PCI device names. Moreover, some operating systems require privileges for probing PCI devices, see Does hwloc require privileged access? for details.

-

The actual locality of I/O devices is only currently detected on Linux. Other operating system will just report I/O devices as being attached to the topology root object.

-

-

-

-

-I/O objects

-

When I/O discovery is enabled and supported, some additional objects are added to the topology. The corresponding I/O object types are:

-

Any of these types may be filtered individually with hwloc_topology_set_type_filter().

-

hwloc tries to attach these new objects to normal objects (usually NUMA nodes) to match their actual physical location. For instance, if a I/O hub (or root complex) is physically connected to a package, the corresponding hwloc bridge object (and its PCI bridges and devices children) is inserted as a child of the corresponding hwloc Package object. These children are not in the normal children list but rather in the I/O-specific children list.

-

I/O objects also have neither CPU sets nor node sets (NULL pointers) because they are not directly usable by the user applications for binding. Moreover I/O hierarchies may be highly complex (asymmetric trees of bridges). So I/O objects are placed in specific levels with custom depths. Their lists may still be traversed with regular helpers such as hwloc_get_next_obj_by_type(). However, hwloc offers some dedicated helpers such as hwloc_get_next_pcidev() and hwloc_get_next_osdev() for convenience (see Finding I/O objects).

-

-

-

-

-OS devices

-

Although each PCI device is uniquely identified by its bus ID (e.g. 0000:01:02.3), a user-space application can hardly find out which PCI device it is actually using. Applications rather use software handles (such as the eth0 network interface, the sda hard drive, or the mlx4_0 OpenFabrics HCA). Therefore hwloc tries to add software devices (HWLOC_OBJ_OS_DEVICE, also known as OS devices).

-

OS devices may be attached below PCI devices, but they may also be attached directly to normal objects. Indeed some OS devices are not related to PCI. For instance, NVDIMM block devices (such as pmem0s on Linux) are directly attached near their NUMA node (I/O child of the parent whose memory child is the NUMA node). Also, if hwloc could not discover PCI for some reason, PCI-related OS devices may also be attached directly to normal objects.

-

Finally, OS subdevices may be exposed as OS devices children of another OS device. This is the case of LevelZero subdevices for instance.

-

hwloc first tries to discover OS devices from the operating system, e.g. eth0, sda or mlx4_0. However, this ability is currently only available on Linux for some classes of devices.

-

hwloc then tries to discover software devices through additional I/O components using external libraries. For instance proprietary graphics drivers do not expose any named OS device, but hwloc may still create one OS object per software handle when supported. For instance the opencl and cuda components may add some opencl0d0 and cuda0 OS device objects.

-

Here is a list of OS device objects commonly created by hwloc components when I/O discovery is enabled and supported.

-
    -
  • -Hard disks or non-volatile memory devices (HWLOC_OBJ_OSDEV_BLOCK)
      -
    • -sda or dax2.0 (Linux component)
      • -
    -
    • -
  • -Network interfaces (HWLOC_OBJ_OSDEV_NETWORK)
      -
    • -eth0, wlan0, ib0 (Linux component)
      • -
    -
    • -
  • -OpenFabrics (InfiniBand, Omni-Path, usNIC, etc) HCAs (HWLOC_OBJ_OSDEV_OPENFABRICS)
      -
    • -mlx5_0, hfi1_0, qib0, usnic_0 (Linux component)
      • -
    • -bxi0 with "BXI" subtype for Atos/Bull BXI HCAs (Linux component) even if those are not really OpenFabrics.
      • -
    -
    • -
  • -GPUs (HWLOC_OBJ_OSDEV_GPU)
      -
    • -rsmi0 for the first RSMI device ("RSMI" subtype, from the RSMI component, using the AMD ROCm SMI library)
      • -
    • -nvml0 for the first NVML device ("NVML" subtype, from the NVML component, using the NVIDIA Management Library)
      • -
    • -:0.0 for the first display ("Display" subtype, from the GL component, using the NV-CONTROL X extension library, NVCtrl)
      • -
    • -card0 and renderD128 for DRM device files (from the Linux component, filtered-out by default because considered non-important)
      • -
    -
    • -
  • -Co-Processors (HWLOC_OBJ_OSDEV_COPROC)
      -
    • -opencl0d0 for the first device of the first OpenCL platform, opencl1d3 for the fourth device of the second OpenCL platform ("OpenCL" subtype, from the OpenCL component)
      • -
    • -ze0 for the first Level Zero device ("LevelZero" subtype, from the levelzero component, using the oneAPI Level Zero library), and ze0.1 for its second subdevice (if any).
      • -
    • -cuda0 for the first NVIDIA CUDA device ("CUDA" subtype, from the CUDA component, using the NVIDIA CUDA Library)
      • -
    • -ve0 for the first NEC Vector Engine device ("VectorEngine" subtype, from the Linux component)
      • -
    -
    • -
  • -DMA engine channel (HWLOC_OBJ_OSDEV_DMA) -
    • -
-

Note that some PCI devices may contain multiple software devices (see the example below).

-

See also Interoperability With Other Software for managing these devices without considering them as hwloc objects.

-

-

-

-

-PCI devices and bridges

-

A PCI hierarchy is usually organized as follows: A hostbridge object ( HWLOC_OBJ_BRIDGE object with upstream type Host and downstream type PCI) is attached below a normal object (usually the entire machine or a NUMA node). There may be multiple hostbridges in the machine, attached to different places, but all PCI devices are below one of them (unless the Bridge object type is filtered-out).

-

Each hostbridge contains one or several children, either other bridges (usually PCI to PCI switches) or PCI devices (HWLOC_OBJ_PCI_DEVICE). The number of bridges between the hostbridge and a PCI device depends on the machine.

-

-

-

-

-Consulting I/O devices and binding

-

I/O devices may be consulted by traversing the topology manually (with usual routines such as hwloc_get_obj_by_type()) or by using dedicated helpers (such as hwloc_get_pcidev_by_busid(), see Finding I/O objects).

-

I/O objects do not actually contain any locality information because their CPU sets and node sets are NULL. Their locality must be retrieved by walking up the object tree (through the parent link) until a non-I/O object is found (see hwloc_get_non_io_ancestor_obj()). This normal object should have non-NULL CPU sets and node sets which describe the processing units and memory that are immediately close to the I/O device. For instance the path from a OS device to its locality may go across a PCI device parent, one or several bridges, up to a Package node with the same locality.

-

Command-line tools are also aware of I/O devices. lstopo displays the interesting ones by default (passing --no-io disables it).

-

hwloc-calc and hwloc-bind may manipulate I/O devices specified by PCI bus ID or by OS device name.

    -
  • -pci=0000:02:03.0 is replaced by the set of CPUs that are close to the PCI device whose bus ID is given.
    • -
  • -os=eth0 is replaced by CPUs that are close to the I/O device whose software handle is called eth0.
    • -
-

This enables easy binding of I/O-intensive applications near the device they use.

-

-

-

-

-Examples

-

The following picture shows a dual-package dual-core host whose PCI bus is connected to the first package and NUMA node.

-
- -
-

Six interesting PCI devices were discovered. However, hwloc found some corresponding software devices (eth0, eth1, sda, mlx4_0, ib0, and ib1) for only four of these physical devices. The other ones (PCI 102b:0532 and PCI 8086:3a20) are an unused IDE controller (no disk attached) and a graphic card (no corresponding software device reported to the user by the operating system).

-

On the contrary, it should be noted that three different software devices were found for the last PCI device (PCI 15b3:634a). Indeed this OpenFabrics HCA PCI device object contains one one OpenFabrics software device (mlx4_0) and two virtual network interface software devices (ib0 and ib1).

-

Here is the corresponding textual output:

-
Machine (24GB total)
-  Package L#0
-    NUMANode L#0 (P#0 12GB)
-    L3 L#0 (8192KB)
-      L2 L#0 (256KB) + L1 L#0 (32KB) + Core L#0 + PU L#0 (P#0)
-      L2 L#1 (256KB) + L1 L#1 (32KB) + Core L#1 + PU L#1 (P#2)
-    HostBridge
-      PCIBridge
-        PCI 01:00.0 (Ethernet)
-          Net "eth0"
-        PCI 01:00.1 (Ethernet)
-          Net "eth1"
-      PCIBridge
-        PCI 03:00.0 (RAID)
-          Block "sda"
-      PCIBridge
-        PCI 04:03.0 (VGA)
-      PCI 00:1f.2 (IDE)
-      PCI 51:00.0 (InfiniBand)
-        Net "ib0"
-        Net "ib1"
-        Net "mlx4_0"
-  Package L#1
-    NUMANode L#1 (P#1 12GB)
-    L3 L#1 (8192KB)
-      L2 L#2 (256KB) + L1 L#2 (32KB) + Core L#2 + PU L#2 (P#1)
-      L2 L#3 (256KB) + L1 L#3 (32KB) + Core L#3 + PU L#3 (P#3)
-
-
- - - - - - -
-
-
-
Miscellaneous objects
-
-
-

-

-

-

hwloc topologies may be annotated with Misc objects (of type HWLOC_OBJ_MISC) either automatically or by the user. This is a flexible way to annotate topologies with large sets of information since Misc objects may be inserted anywhere in the topology (to annotate specific objects or parts of the topology), even below other Misc objects, and each of them may contain multiple attributes (see also How do I annotate the topology with private notes?).

-

These Misc objects may have a subtype field to replace Misc with something else in the lstopo output.

-

-

-

-

-Misc objects added by hwloc

-

hwloc only uses Misc objects when other object types are not sufficient, and when the Misc object type is not filtered-out anymore. This currently includes:

    -
  • -Memory modules (DIMMs), on Linux when privileged and when dmi-sysfs is supported by the kernel. These objects have a subtype field of value MemoryModule. They are currently always attached to the root object. Their attributes describe the DIMM vendor, model, etc. lstopo -v displays them as:
    Misc(MemoryModule) (P#1 DeviceLocation="Bottom-Slot 2(right)" BankLocation="BANK 2" Vendor=Elpida SerialNumber=21733667 AssetTag=9876543210 PartNumber="EBJ81UG8EFU0-GN-F ")
    -
    • -
  • -Displaying process binding in lstopo --top. These objects have a subtype field of value Process and a name attribute made of their PID and program name. They are attached below the object they are bound to. The textual lstopo displays them as:
    PU L#0 (P#0)
    -
    Misc(Process) 4445 myprogram
    -
    • -
-

-

-

-

-Annotating topologies with Misc objects

-

The user may annotate hwloc topologies with its own Misc objects. This can be achieved with hwloc_topology_insert_misc_object() as well as hwloc-annotate command-line tool.

-
-
- - - - - - -
-
-
-
Object attributes
-
-
-

-

-

-

-Normal attributes

-

hwloc objects have many generic attributes in the hwloc_obj structure, for instance their logical_index or os_index (see Should I use logical or physical/OS indexes? and how?), depth or name.

-

The kind of object is first described by the obj->type generic attribute (an integer). OS devices also have a specific obj->attr->osdev.type integer for distinguishing between NICs, GPUs, etc.

-

Objects may also have an optional obj->subtype pointing to a better description string (displayed by lstopo either in place or after the main obj->type attribute):

    -
  • -NUMA nodes: subtype DRAM (for usual main memory), HBM (high-bandwidth memory), SPM (specific-purpose memory, usually reserved for some custom applications), NVM (non-volatile memory when used as main memory), MCDRAM (on KNL) or GPUMemory (on POWER architecture with NVIDIA GPU memory shared over NVLink).
    • -
  • -Groups: subtype Cluster, Module, Tile, Compute Unit, Book or Drawer for different architecture-specific groups of CPUs (see also What are these Group objects in my topology?).
    • -
  • -OS devices (see also OS devices):
      -
    • -Co-processor: subtype OpenCL, LevelZero, CUDA, or VectorEngine.
      • -
    • -GPU: subtype RSMI (AMD GPU) or NVML (NVIDIA GPU).
      • -
    • -OpenFabrics: subtype BXI (Bull/Atos BXI HCA).
      • -
    • -Block: subtype Disk, NVM (non-volatile memory), SPM (specific-purpose memory), CXLMem (CXL volatile ou persistent memory), Tape, or Removable Media Device.
      • -
    -
    • -
  • -L3 Caches: subtype MemorySideCache when hwloc is configured to expose the KNL MCDRAM in Cache mode as a L3.
    • -
  • -PCI devices: subtype NVSwitch for NVLink switches (see also NVLinkBandwidth in Distances).
    • -
  • -Misc devices: subtype MemoryModule (see also Misc objects added by hwloc)
    • -
-

Each object also contains an attr field that, if non NULL, points to a union hwloc_obj_attr_u of type-specific attribute structures. For instance, a L2Cache object obj contains cache-specific information in obj->attr->cache, such as its size and associativity, cache type. See hwloc_obj_attr_u for details.

-

-

-

-

-Custom string infos

-

Aside os these generic attribute fields, hwloc annotates many objects with string attributes that are made of a key and a value. Each object contains a list of such pairs that may be consulted manually (looking at the object infos array field) or using the hwloc_obj_get_info_by_name(). The user may additionally add new key-value pairs to any object using hwloc_obj_add_info() or the hwloc-annotate program.

-

Here is a non-exhaustive list of attributes that may be automatically added by hwloc. Note that these attributes heavily depend on the ability of the operating system to report them. Many of them will therefore be missing on some OS.

-

-

-

-

-Hardware Platform Information

-

These info attributes are attached to the root object (Machine).

-
-
PlatformName, PlatformModel, PlatformVendor, PlatformBoardID, PlatformRevision,
-
-
SystemVersionRegister, ProcessorVersionRegister (Machine)
-
Some POWER/PowerPC-specific attributes describing the platform and processor. Currently only available on Linux. Usually added to Package objects, but can be in Machine instead if hwloc failed to discover any package.
-
DMIBoardVendor, DMIBoardName, etc.
-
DMI hardware information such as the motherboard and chassis models and vendors, the BIOS revision, etc., as reported by Linux under /sys/class/dmi/id/.
-
MemoryMode, ClusterMode
-

Intel Xeon Phi processor configuration modes. Available if hwloc-dump-hwdata was used (see Why do I need hwloc-dump-hwdata for memory on Intel Xeon Phi processor?) or if hwloc managed to guess them from the NUMA configuration.

-

The memory mode may be Cache, Flat, Hybrid50 (half the MCDRAM is used as a cache) or Hybrid25 (25% of MCDRAM as cache). The cluster mode may be Quadrant, Hemisphere, All2All, SNC2 or SNC4. See doc/examples/get-knl-modes.c in the source directory for an example of retrieving these attributes.

-
-
-

-

-

-

-Operating System Information

-

These info attributes are attached to the root object (Machine).

-
-
OSName, OSRelease, OSVersion, HostName, Architecture
-
The operating system name, release, version, the hostname and the architecture name, as reported by the Unix uname command.
-
LinuxCgroup
-
The name the Linux control group where the calling process is placed.
-
WindowsBuildEnvironment
-
Either MinGW or Cygwin when one of these environments was used during build.
-
-

-

-

-

-hwloc Information

-

Unless specified, these info attributes are attached to the root object (Machine).

-
-
Backend (topology root, or specific object added by that backend)
-
The name of the hwloc backend/component that filled the topology. If several components were combined, multiple Backend keys may exist, with different values, for instance x86 and Linux in the root object and CUDA in CUDA OS device objects.
-
SyntheticDescription
-
The description string that was given to hwloc to build this synthetic topology.
-
hwlocVersion
-
The version number of the hwloc library that was used to generate the topology. If the topology was loaded from XML, this is not the hwloc version that loaded it, but rather the first hwloc instance that exported the topology to XML earlier.
-
ProcessName
-
The name of the process that contains the hwloc library that was used to generate the topology. If the topology was from XML, this is not the hwloc process that loaded it, but rather the first process that exported the topology to XML earlier.
-
-

-

-

-

-CPU Information

-

These info attributes are attached to Package objects, or to the root object (Machine) if package locality information is missing.

-
-
CPUModel
-
The processor model name.
-
CPUVendor, CPUModelNumber, CPUFamilyNumber, CPUStepping
-
The processor vendor name, model number, family number, and stepping number. Currently available for x86 and Xeon Phi processors on most systems, and for ia64 processors on Linux (except CPUStepping).
-
CPURevision
-
A POWER/PowerPC-specific general processor revision number, currently only available on Linux.
-
CPUType
-
A Solaris-specific general processor type name, such as "i86pc".
-
-

-

-

-

-OS Device Information

-

These info attributes are attached to OS device objects specified in parentheses.

-
-
Vendor, Model, Revision, SerialNumber, Size, SectorSize (Block OS devices)
-
The vendor and model names, revision, serial number, size (in KiB = 1024 bytes) and SectorSize (in bytes).
-
LinuxDeviceID (Block OS devices)
-
The major/minor device number such as 8:0 of Linux device.
-
CXLRAMSize, CXLPMEMSize (CXL Memory Block OS devices)
-
The size of the volatile (RAM) or persistent (PMEM) memory in a CXL Type-3 device . Sizes are in KiB (1024 bytes).
-
GPUVendor, GPUModel (GPU or Co-Processor OS devices)
-
The vendor and model names of the GPU device.
-
OpenCLDeviceType, OpenCLPlatformIndex,
-
-
OpenCLPlatformName, OpenCLPlatformDeviceIndex (OpenCL OS devices)
-
The type of OpenCL device, the OpenCL platform index and name, and the index of the device within the platform.
-
OpenCLComputeUnits, OpenCLGlobalMemorySize (OpenCL OS devices)
-
The number of compute units and global memory size of an OpenCL device. Sizes are in KiB (1024 bytes).
-
LevelZeroVendor, LevelZeroModel, LevelZeroBrand,
-
-
LevelZeroSerialNumber, LevelZeroBoardNumber (LevelZero OS devices)
-
The name of the vendor, device model, brand of a Level Zero device, and its serial and board numbers.
-
LevelZeroDriverIndex, LevelZeroDriverDeviceIndex (LevelZero OS devices)
-
The index of the Level Zero driver within the list of drivers, and the index of the device within the list of devices managed by this driver.
-
LevelZeroUUID (LevelZero OS devices or subdevices)
-
The UUID of the device or subdevice.
-
LevelZeroSubdevices (LevelZero OS devices)
-
The number of subdevices below this OS device.
-
LevelZeroSubdeviceID (LevelZero OS subdevices)
-
The index of this subdevice within its parent.
-
LevelZeroDeviceType (LevelZero OS devices or subdevices)
-
A string describing the type of device, for instance "GPU", "CPU", "FPGA", etc.
-
LevelZeroNumSlices, LevelZeroNumSubslicesPerSlice,
-
-
LevelZeroNumEUsPerSubslice, LevelZeroNumThreadsPerEU (LevelZero OS devices or subdevices)
-
The number of slices in the device, of subslices per slice, of execution units (EU) per subslice, and of threads per EU.
-
LevelZeroHBMSize, LevelZeroDDRSize, LevelZeroMemorySize (LevelZero OS devices or subdevices)
-
The amount of HBM or DDR memory of a LevelZero device or subdevice. Sizes are in KiB (1024 bytes). If the type of memory could not be determined, the generic name LevelZeroMemorySize is used. For devices that contain subdevices, the amount reported in the root device includes the memories of all its subdevices.
-
LevelZeroCQGroups, LevelZeroCQGroup2 (LevelZero OS devices or subdevices)
-
The number of completion queue groups, and the description of the third group (as N*0xX where N is the number of queues in the group, and 0xX is the hexadecimal bitmask of ze_command_queue_group_property_flag_t listing properties of those queues).
-
AMDUUID, AMDSerial (RSMI GPU OS devices)
-
The UUID and serial number of AMD GPUs.
-
RSMIVRAMSize, RSMIVisibleVRAMSize, RSMIGTTSize (RSMI GPU OS devices)
-
The amount of GPU memory (VRAM), of GPU memory that is visible from the host (Visible VRAM), and of system memory that is usable by the GPU (Graphics Translation Table). Sizes are in KiB (1024 bytes).
-
XGMIHiveID (RSMI GPU OS devices)
-
The ID of the group of GPUs (Hive) interconnected by XGMI links
-
XGMIPeers (RSMI GPU OS devices)
-
The list of RSMI OS devices that are directly connected to the current device through XGMI links. They are given as a space-separated list of object names, for instance rsmi2 rsmi3.
-
NVIDIAUUID, NVIDIASerial (NVML GPU OS devices)
-
The UUID and serial number of NVIDIA GPUs.
-
CUDAMultiProcessors, CUDACoresPerMP,
-
-
CUDAGlobalMemorySize, CUDAL2CacheSize, CUDASharedMemorySizePerMP (CUDA OS devices)
-
The number of shared multiprocessors, the number of cores per multiprocessor, the global memory size, the (global) L2 cache size, and size of the shared memory in each multiprocessor of a CUDA device. Sizes are in KiB (1024 bytes).
-
VectorEngineModel, VectorEngineSerialNumber (VectorEngine OS devices)
-
The model and serial number of a VectorEngine device.
-
VectorEngineCores, VectorEngineMemorySize, VectorEngineLLCSize,
-
-
VectorEngineL2Size, VectorEngineL1dSize, VectorEngineL1iSize (VectorEngine OS devices)
-
The number of cores, memory size, and the sizes of the (global) last level cache and of L2, L1d and L1i caches of a VectorEngine device. Sizes are in KiB (1024 bytes).
-
VectorEngineNUMAPartitioned (VectorEngine OS devices)
-
If this attribute exists, the VectorEngine device is configured in partitioned mode with multiple NUMA nodes.
-
Address, Port (Network interface OS devices)
-
The MAC address and the port number of a software network interface, such as eth4 on Linux.
-
NodeGUID, SysImageGUID, Port1State, Port2LID, Port2LMC, Port3GID1 (OpenFabrics OS devices)
-
The node GUID and GUID mask, the state of a port #1 (value is 4 when active), the LID and LID mask count of port #2, and GID #1 of port #3.
-
BXIUUID (OpenFabrics BXI OS devices)
-
The UUID of an Atos/Bull BXI HCA.
-
-

-

-

-

-Other Object-specific Information

-

These info attributes are attached to objects specified in parentheses.

-
-
DAXDevice (NUMA Nodes)
-
The name of the Linux DAX device that was used to expose a non-volatile memory region as a volatile NUMA node.
-
DAXType (NUMA Nodes or DAX OS devices)
-
The type of memory exposed in a Linux DAX device or in the corresponding NUMA node, either "NVM" (non-volatile memory) or "SPM" (specific-purpose memory).
-
DAXParent (NUMA Nodes or DAX OS devices)
-
A string describing the Linux sysfs hierarchy that exposes the DAX device, for instance containing "hmem1" for specific-purpose memory or "ndbus0" for NVDIMMs.
-
-
-
PCIBusID (GPUMemory NUMA Nodes)
-
The PCI bus ID of the GPU whose memory is exposed in this NUMA node.
-
Inclusive (Caches)
-
The inclusiveness of a cache (1 if inclusive, 0 otherwise). Currently only available on x86 processors.
-
SolarisProcessorGroup (Group)
-
The Solaris kstat processor group name that was used to build this Group object.
-
PCIVendor, PCIDevice (PCI devices and bridges)
-
The vendor and device names of the PCI device.
-
PCISlot (PCI devices or Bridges)
-
The name/number of the physical slot where the device is plugged. If the physical device contains PCI bridges above the actual PCI device, the attribute may be attached to the highest bridge (i.e. the first object that actually appears below the physical slot).
-
Vendor, AssetTag, PartNumber, DeviceLocation, BankLocation (MemoryModule Misc objects)
-
Information about memory modules (DIMMs) extracted from SMBIOS.
-
-

-

-

-

-User-Given Information

-

Here is a non-exhaustive list of user-provided info attributes that have a special meaning:

-
lstopoStyle
-
Enforces the style of an object (background and text colors) in the graphical output of lstopo. See CUSTOM COLORS in the lstopo(1) manpage for details.
-
-
-
- - - - - - -
-
-
-
Topology Attributes: Distances, Memory Attributes and CPU Kinds
-
-
-

-

-

-

Besides the hierarchy of objects and individual object attributes (see Object attributes), hwloc may also expose finer information about the hardware organization.

-

-

-

-

-Distances

-

A machine with 4 CPUs may have identical links between every pairs of CPUs, or those CPUs could also only be connected through a ring. In the ring case, accessing the memory of nearby CPUs is slower than local memory, but it is also faster than accessing the memory of CPU on the opposite side of the ring. These deep details cannot be exposed in the hwloc hierarchy, that is why hwloc also exposes distances.

-

Distances are matrices of values between sets of objects, usually latencies or bandwidths. By default, hwloc tries to get a matrix of relative latencies between NUMA nodes when exposed by the hardware.

-

In the aforementioned ring case, the matrix could report 10 for latency between a NUMA node and itself, 20 for nearby nodes, and 30 for nodes that are opposites on the ring. Those are theoretical values exposed by hardware vendors (in the System Locality Distance Information Table (SLIT) in the ACPI) rather than physical latencies. They are mostly meant for comparing node relative distances.

-

Distances structures currently created by hwloc are:

-
NUMALatency (Linux, Solaris, FreeBSD)
-
This is the matrix of theoretical latencies described above.
-
XGMIBandwidth (RSMI)
-

This is the matrix of unidirectional XGMI bandwidths between AMD GPUs (in MB/s). It contains 0 when there is no direct XGMI link between objects. Values on the diagonal are artificially set to very high so that local access always appears faster than remote access.

-

GPUs are identified by RSMI OS devices such as "rsmi0". They may be converted into the corresponding OpenCL or PCI devices using hwloc_get_obj_with_same_locality() or the hwloc-annotate tool.

-

hwloc_distances_transform() or hwloc-annotate may also be used to transform this matrix into something more convenient, for instance by replacing bandwidths with numbers of links between peers.

-
-
XGMIHops (RSMI)
-
This matrix lists the number of XGMI hops between AMD GPUs. It reports 1 when there is a direct link between two distinct GPUs. If there is no XGMI route between them, the value is 0. The number of hops between a GPU and itself (on the diagonal) is 0 as well.
-
XeLinkBandwidth (LevelZero)
-

This is the matrix of unidirectional XeLink bandwidths between Intel GPUs (in MB/s). It contains 0 when there is no direct XeLink between objects. When there are multiple links, their bandwidth is aggregated.

-

Values on the diagonal are artificially set to very high so that local access always appears faster than remote access. This includes bandwidths between a (sub)device and itself, between a subdevice and its parent device, or between two subdevices of the same parent.

-

The matrix interconnects all LevelZero devices and subdevices (if any), even if some of them may have no link at all.

-
-
NVLinkBandwidth (NVML)
-

This is the matrix of unidirectional NVLink bandwidths between NVIDIA GPUs (in MB/s). It contains 0 when there is no direct NVLink between objects. When there are multiple links, their bandwidth is aggregated. Values on the diagonal are artificially set to very high so that local access always appears faster than remote access.

-

On POWER platforms, NVLinks may also connects GPUs to CPUs. On NVIDIA platforms such as DGX-2, a NVSwitch may interconnect GPUs through NVLinks. In these cases, the distances structure is heterogeneous. GPUs always appear first in the matrix (as NVML OS devices such as "nvml0"), and non-GPU objects may appear at the end (Package for POWER processors, PCI device for NVSwitch).

-

NVML OS devices may be converted into the corresponding CUDA, OpenCL or PCI devices using hwloc_get_obj_with_same_locality() or the hwloc-annotate tool.

-

hwloc_distances_transform() or hwloc-annotate may also be used to transform this matrix into something more convenient, for instance by removing switches or CPU ports, or by replacing bandwidths with numbers of links between peers.

-

When a NVSwitch interconnects GPUs, only links between one GPU and different NVSwitch ports are reported. They may be merged into a single switch port with hwloc_distances_transform() or hwloc-annotate. Or a transitive closure may also be applied to report the bandwidth between GPUs across the NVSwitch.

-
-
-

Users may also specify their own matrices between any set of objects, even if these objects are of different types (e.g. bandwidths between GPUs and CPUs).

-

The entire API is located in hwloc/distances.h. See also Retrieve distances between objects, as well as Helpers for consulting distance matrices and Add distances between objects.

-

-

-

-

-Memory Attributes

-

Machines with heterogeneous memory, for instance high-bandwidth memory (HBM), normal memory (DDR), and/or high-capacity slow memory (such as non-volatile memory DIMMs, NVDIMMs) require applications to allocate buffers in the appropriate target memory depending on performance and capacity needs. Those target nodes may be exposed in the hwloc hierarchy as different memory children but there is a need for performance information to select the appropriate one.

-

hwloc memory attributes are designed to expose memory information such as latency, bandwidth, etc. Users may also specify their own attributes and values.

-

The memory attributes API is located in hwloc/memattrs.h, see Comparing memory node attributes for finding where to allocate on and Managing memory attributes for details. See also an example in doc/examples/memory-attributes.c in the source tree.

-

-

-

-

-CPU Kinds

-

Hybrid CPUs may contain different kinds of cores. The CPU kinds API in hwloc/cpukinds.h provides a way to list the sets of PUs in each kind and get some optional information about their hardware characteristics and efficiency.

-

If the operating system provides efficiency information (e.g. Windows 10, MacOS X / Darwin and some Linux kernels), it is used to rank hwloc CPU kinds by efficiency. Otherwise, hwloc implements several heuristics based on frequencies and core types (see HWLOC_CPUKINDS_RANKING in Environment Variables).

-

The ranking shows energy-efficient CPUs first, and high-performance power-hungry cores last.

-

These CPU kinds may be annotated with the following native attributes:

-
FrequencyMaxMHz (Linux)
-
The maximal operating frequency of the core, as reported by cpufreq drivers on Linux.
-
FrequencyBaseMHz (Linux)
-
The base operating frequency of the core, as reported by some cpufreq drivers on Linux (e.g. intel_pstate).
-
CoreType (x86)
-
A string describing the kind of core, currently IntelAtom or IntelCore, as reported by the x86 CPUID instruction on some Intel processors.
-
LinuxCapacity (Linux)
-
The Linux-specific CPU capacity found in sysfs, as reported by the Linux kernel on some recent platforms. Higher values usually mean that the Linux scheduler considers the core as high-performance rather than energy-efficient.
-
LinuxCPUType (Linux)
-
The Linux-specific CPU type found in sysfs, such as intel_atom_0, as reported by future Linux kernels on some Intel processors.
-
DarwinCompatible (Darwin / Mac OS X)
-
The compatibility attribute of the CPUs as found in the IO registry on Darwin / Mac OS X. For instance apple,icestorm;ARM,v8 for energy-efficient cores and apple,firestorm;ARM,v8 on performance cores on Apple M1 CPU.
-
-

See Kinds of CPU cores for details.

-
-
- - - - - - -
-
-
-
Importing and exporting topologies from/to XML files
-
-
-

-

-

-

hwloc offers the ability to export topologies to XML files and reload them later. This is for instance useful for loading topologies faster (see I do not want hwloc to rediscover my enormous machine topology every time I rerun a process), manipulating other nodes' topology, or avoiding the need for privileged processes (see Does hwloc require privileged access?).

-

Topologies may be exported to XML files thanks to hwloc_topology_export_xml(), or to a XML memory buffer with hwloc_topology_export_xmlbuffer(). The lstopo program can also serve as a XML topology export tool.

-

XML topologies may then be reloaded later with hwloc_topology_set_xml() and hwloc_topology_set_xmlbuffer(). The HWLOC_XMLFILE environment variable also tells hwloc to load the topology from the given XML file (see Environment Variables).

-
Note
Loading XML topologies disables binding because the loaded topology may not correspond to the physical machine that loads it. This behavior may be reverted by asserting that loaded file really matches the underlying system with the HWLOC_THISSYSTEM environment variable or the HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM topology flag.
-
-The topology flag HWLOC_TOPOLOGY_FLAG_THISSYSTEM_ALLOWED_RESOURCES may be used to load a XML topology that contains the entire machine and restrict it to the part that is actually available to the current process (e.g. when Linux Cgroup/Cpuset are used to restrict the set of resources).
-
-hwloc also offers the ability to export/import Topology differences.
-
-XML topology files are not localized. They use a dot as a decimal separator. Therefore any exported topology can be reloaded on any other machine without requiring to change the locale.
-
-XML exports contain all details about the platform. It means that two very similar nodes still have different XML exports (e.g. some serial numbers or MAC addresses are different). If a less precise exporting/importing is required, one may want to look at Synthetic topologies instead.
-

-

-

-

-libxml2 and minimalistic XML backends

-

hwloc offers two backends for importing/exporting XML.

-

First, it can use the libxml2 library for importing/exporting XML files. It features full XML support, for instance when those files have to be manipulated by non-hwloc software (e.g. a XSLT parser). The libxml2 backend is enabled by default if libxml2 development headers are available (the relevant development package is usually libxml2-devel or libxml2-dev).

-

If libxml2 is not available at configure time, or if --disable-libxml2 is passed, hwloc falls back to a custom backend. Contrary to the aforementioned full XML backend with libxml2, this minimalistic XML backend cannot be guaranteed to work with external programs. It should only be assumed to be compatible with the same hwloc release (even if using the libxml2 backend). Its advantage is, however, to always be available without requiring any external dependency.

-

If libxml2 is available but the core hwloc library should not directly depend on it, the libxml2 support may be built as a dynamicall-loaded plugin. One should pass --enable-plugins to enable plugin support (when supported) and build as plugins all component that support it. Or pass --enable-plugins=xml_libxml to only build this libxml2 support as a plugin.

-

-

-

-

-XML import error management

-

Importing XML files can fail at least because of file access errors, invalid XML syntax, non-hwloc-valid XML contents, or incompatibilities between hwloc releases (see Are XML topology files compatible between hwloc releases?).

-

Both backend cannot detect all these errors when the input XML file or buffer is selected (when hwloc_topology_set_xml() or hwloc_topology_set_xmlbuffer() is called). Some errors such non-hwloc-valid contents can only be detected later when loading the topology with hwloc_topology_load().

-

It is therefore strongly recommended to check the return value of both hwloc_topology_set_xml() (or hwloc_topology_set_xmlbuffer()) and hwloc_topology_load() to handle all these errors.

-
-
- - - - - - -
-
-
-
Synthetic topologies
-
-
-

-

-

-

hwloc may load fake or remote topologies so as to consult them without having the underlying hardware available. Aside from loading XML topologies, hwloc also enables the building of synthetic topologies that are described by a single string listing the arity of each levels.

-

For instance, lstopo may create a topology made of 2 packages, containing a single NUMA node and a L2 cache above two single-threaded cores:

-
$ lstopo -i "pack:2 node:1 l2:1 core:2 pu:1" -
-Machine (2048MB)
-  Package L#0
-    NUMANode L#0 (P#0 1024MB)
-    L2 L#0 (4096KB)
-      Core L#0 + PU L#0 (P#0)
-      Core L#1 + PU L#1 (P#1)
-  Package L#1
-    NUMANode L#1 (P#1 1024MB)
-    L2 L#1 (4096KB)
-      Core L#2 + PU L#2 (P#2)
-      Core L#3 + PU L#3 (P#3)
-

Replacing - with file.xml in this command line will export this topology to XML as usual.

-
Note
Synthetic topologies offer a very basic way to export a topology and reimport it on another machine. It is a lot less precise than XML but may still be enough when only the hierarchy of resources matters.
-

-

-

-

-Synthetic description string

-

Each item in the description string gives the type of the level and the number of such children under each object of the previous level. That is why the above topology contains 4 cores (2 cores times 2 nodes).

-

These type names must be written as numanode, package, core, l2u, l1i, pu, group (hwloc_obj_type_sscanf() is used for parsing the type names). They do not need to be written case-sensitively, nor entirely (as long as there is no ambiguity, 2 characters such as ma select a Machine level). Note that I/O and Misc objects are not available.

-

Instead of specifying the type of each level, it is possible to just specify the arities and let hwloc choose all types according to usual topologies. The following examples are therefore equivalent: 

$ lstopo -i "2 3 4 5 6"
-$ lstopo -i "Package:2 NUMANode:3 L2Cache:4 Core:5 PU:6"
-

NUMA nodes are handled in a special way since they are not part of the main CPU hierarchy but rather attached below it as memory children. Thus, NUMANode:3 actually means Group:3 where one NUMA node is attached below each group. These groups are merged back into the parent when possible (typically when a single NUMA node is requested below each parent).

-

It is also possible the explicitly attach NUMA nodes to specific levels. For instance, a topology similar to a Intel Xeon Phi processor (with 2 NUMA nodes per 16-core group) may be created with: 

$ lstopo -i "package:1 group:4 [numa] [numa] core:16 pu:4"
-

The root object does not appear in the synthetic description string since it is always a Machine object. Therefore the Machine type is disallowed in the description as well.

-

A NUMA level (with a single NUMA node) is automatically added if needed.

-

Each item may be followed parentheses containing a list of space-separated attributes. For instance:

    -
  • -L2iCache:2(size=32kB) specifies 2 children of 32kB level-2 instruction caches. The size may be specified in bytes (without any unit suffix) or as kB, KiB, MB, MiB, etc.
    • -
  • -NUMANode:3(memory=16MB) specifies 3 NUMA nodes with 16MB each. The size may be specified in bytes (without any unit suffix) or as GB, GiB, TB, TiB, etc.
    • -
  • -PU:2(indexes=0,2,1,3) specifies 2 PU children and the full list of OS indexes among the entire set of 4 PU objects.
    • -
  • -PU:2(indexes=numa:core) specifies 2 PU children whose OS indexes are interleaved by NUMA node first and then by package.
    • -
  • -Attributes in parentheses at the very beginning of the description apply to the root object.
    • -
-

hwloc command-line tools may modify a synthetic topology, for instance to customize object attributes, or to remove some objects to make the topology heterogeneous or asymmetric. See many examples in How do I create a custom heterogeneous and asymmetric topology?.

-

-

-

-

-Loading a synthetic topology

-

Aside from lstopo, the hwloc programming interface offers the same ability by passing the synthetic description string to hwloc_topology_set_synthetic() before hwloc_topology_load().

-

Synthetic topologies are created by the synthetic component. This component may be enabled by force by setting the HWLOC_SYNTHETIC environment variable to something such as node:2 core:3 pu:4.

-

Loading a synthetic topology disables binding support since the topology usually does not match the underlying hardware. Binding may be reenabled as usual by setting HWLOC_THISSYSTEM=1 in the environment or by setting the HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM topology flag.

-

-

-

-

-Exporting a topology as a synthetic string

-

The function hwloc_topology_export_synthetic() may export a topology as a synthetic string. It offers a convenient way to quickly describe the contents of a machine. The lstopo tool may also perform such an export by forcing the output format.

-
$ lstopo --of synthetic --no-io
-Package:1 L3Cache:1 L2Cache:2 L1dCache:1 L1iCache:1 Core:1 PU:2
-

The exported string may be passed back to hwloc for recreating another similar topology (see also Are synthetic strings compatible between hwloc releases?). The entire tree will be similar, but some attributes such as the processor model will be missing.

-

Such an export is only possible if the topology is totally symmetric. It means that the symmetric_subtree field of the root object is set. Also memory children should be attached in a symmetric way (e.g. the same number of memory children below each Package object, etc.). However, I/O devices and Misc objects are ignored when looking at symmetry and exporting the string.

-
-
- - - - - - -
-
-
-
Interoperability With Other Software
-
-
-

-

-

-

Although hwloc offers its own portable interface, it still may have to interoperate with specific or non-portable libraries that manipulate similar kinds of objects. hwloc therefore offers several specific "helpers" to assist converting between those specific interfaces and hwloc.

-

Some external libraries may be specific to a particular OS; others may not always be available. The hwloc core therefore generally does not explicitly depend on these types of libraries. However, when a custom application uses or otherwise depends on such a library, it may optionally include the corresponding hwloc helper to extend the hwloc interface with dedicated helpers.

-

Most of these helpers use structures that are specific to these external libraries and only meaningful on the local machine. If so, the helper requires the input topology to match the current machine. Some helpers also require I/O device discovery to be supported and enabled for the current topology.

-
-
Linux specific features
-

hwloc/linux.h offers Linux-specific helpers that utilize some non-portable features of the Linux system, such as binding threads through their thread ID ("tid") or parsing kernel CPU mask files. See Linux-specific helpers.

-

-
-
Windows specific features
-

hwloc/windows.h offers Windows-specific helpers to query information about Windows processor groups. See Windows-specific helpers.

-

-
-
Linux libnuma
-

hwloc/linux-libnuma.h provides conversion helpers between hwloc CPU sets and libnuma-specific types, such as bitmasks. It helps you use libnuma memory-binding functions with hwloc CPU sets. See Interoperability with Linux libnuma bitmask and Interoperability with Linux libnuma unsigned long masks.

-

-
-
Glibc
-

hwloc/glibc-sched.h offers conversion routines between Glibc and hwloc CPU sets in order to use hwloc with functions such as sched_getaffinity() or pthread_attr_setaffinity_np(). See Interoperability with glibc sched affinity.

-

-
-
OpenFabrics Verbs
-

hwloc/openfabrics-verbs.h helps interoperability with the OpenFabrics Verbs interface. For example, it can return a list of processors near an OpenFabrics device. It may also return the corresponding OS device hwloc object for further information (if I/O device discovery is enabled). See Interoperability with OpenFabrics.

-

-
-
OpenCL
-

hwloc/opencl.h enables interoperability with the OpenCL interface. Only the AMD and NVIDIA implementations currently offer locality information. It may return the list of processors near a GPU given as a cl_device_id. It may also return the corresponding OS device hwloc object for further information (if I/O device discovery is enabled). See Interoperability with OpenCL.

-

-
-
oneAPI Level Zero
-

hwloc/levelzero.h enables interoperability with the oneAPI Level Zero interface. It may return the list of processors near an accelerator or GPU. It may also return the corresponding OS device hwloc object for further information (if I/O device discovery is enabled). See Interoperability with the oneAPI Level Zero interface..

-

-
-
AMD ROCm SMI Library (RSMI)
-

hwloc/rsmi.h enables interoperability with the AMD ROCm SMI interface. It may return the list of processors near an AMD GPU. It may also return the corresponding OS device hwloc object for further information (if I/O device discovery is enabled). See Interoperability with the ROCm SMI Management Library.

-

-
-
NVIDIA CUDA
-

hwloc/cuda.h and hwloc/cudart.h enable interoperability with NVIDIA CUDA Driver and Runtime interfaces. For instance, it may return the list of processors near NVIDIA GPUs. It may also return the corresponding OS device hwloc object for further information (if I/O device discovery is enabled). See Interoperability with the CUDA Driver API and Interoperability with the CUDA Runtime API.

-

-
-
NVIDIA Management Library (NVML)
-

hwloc/nvml.h enables interoperability with the NVIDIA NVML interface. It may return the list of processors near a NVIDIA GPU given as a nvmlDevice_t. It may also return the corresponding OS device hwloc object for further information (if I/O device discovery is enabled). See Interoperability with the NVIDIA Management Library.

-

-
-
NVIDIA displays
-

hwloc/gl.h enables interoperability with NVIDIA displays using the NV-CONTROL X extension (NVCtrl library). If I/O device discovery is enabled, it may return the OS device hwloc object that corresponds to a display given as a name such as :0.0 or given as a port/device pair (server/screen). See Interoperability with OpenGL displays.

-

-
-
Taskset command-line tool
-

The taskset command-line tool is widely used for binding processes. It manipulates CPU set strings in a format that is slightly different from hwloc's one (it does not divide the string in fixed-size subsets and separates them with commas). To ease interoperability, hwloc offers routines to convert hwloc CPU sets from/to taskset-specific string format. See for instance hwloc_bitmap_taskset_snprintf() in The bitmap API.

-

Most hwloc command-line tools also support the --taskset option to manipulate taskset-specific strings.

-

-
-
-
-
- - - - - - -
-
-
-
Thread Safety
-
-
-

-

-

-

Like most libraries that mainly fill data structures, hwloc is not thread safe but rather reentrant: all state is held in a hwloc_topology_t instance without mutex protection. That means, for example, that two threads can safely operate on and modify two different hwloc_topology_t instances, but they should not simultaneously invoke functions that modify the same instance. Similarly, one thread should not modify a hwloc_topology_t instance while another thread is reading or traversing it. However, two threads can safely read or traverse the same hwloc_topology_t instance concurrently.

-

When running in multiprocessor environments, be aware that proper thread synchronization and/or memory coherency protection is needed to pass hwloc data (such as hwloc_topology_t pointers) from one processor to another (e.g., a mutex, semaphore, or a memory barrier). Note that this is not a hwloc-specific requirement, but it is worth mentioning.

-

For reference, hwloc_topology_t modification operations include (but may not be limited to):

-
-
Creation and destruction
-

hwloc_topology_init(), hwloc_topology_load(), hwloc_topology_destroy() (see Topology Creation and Destruction) imply major modifications of the structure, including freeing some objects. No other thread cannot access the topology or any of its objects at the same time.

-

Also references to objects inside the topology are not valid anymore after these functions return.

-

-
-
Runtime topology modifications
-

hwloc_topology_insert_misc_object(), hwloc_topology_alloc_group_object(), and hwloc_topology_insert_group_object() (see Modifying a loaded Topology) may modify the topology significantly by adding objects inside the tree, changing the topology depth, etc.

-

hwloc_distances_add_commit() and hwloc_distances_remove() (see Add distances between objects) modify the list of distance structures in the topology, and the former may even insert new Group objects.

-

hwloc_memattr_register() and hwloc_memattr_set_value() (see Managing memory attributes) modify the memory attributes of the topology.

-

hwloc_topology_restrict() modifies the topology even more dramatically by removing some objects.

-

hwloc_topology_refresh() updates some internal cached structures. (see below).

-

Although references to former objects may still be valid after insertion or restriction, it is strongly advised to not rely on any such guarantee and always re-consult the topology to reacquire new instances of objects.

-

-
-
Consulting distances
-

hwloc_distances_get() and its variants are thread-safe except if the topology was recently modified (because distances may involve objects that were removed).

-

Whenever the topology is modified (see above), hwloc_topology_refresh() should be called in the same thread-safe context to force the refresh of internal distances structures. A call to hwloc_distances_get() may also refresh distances-related structures.

-

Once this refresh has been performed, multiple hwloc_distances_get() may then be performed concurrently by multiple threads.

-

-
-
Consulting memory attributes
-

Functions consulting memory attributes in hwloc/memattrs.h are thread-safe except if the topology was recently modified (because memory attributes may involve objects that were removed).

-

Whenever the topology is modified (see above), hwloc_topology_refresh() should be called in the same thread-safe context to force the refresh of internal memory attribute structures. A call to hwloc_memattr_get_value() or hwloc_memattr_get_targets() may also refresh internal structures for a given memory attribute.

-

Once this refresh has been performed, multiple functions consulting memory attributes may then be performed concurrently by multiple threads.

-

-
-
Locating topologies
-

hwloc_topology_set_* (see Topology Detection Configuration and Query) do not modify the topology directly, but they do modify internal structures describing the behavior of the upcoming invocation of hwloc_topology_load(). Hence, all of these functions should not be used concurrently.

-

-
-
-
-
- - - - - - -
-
-
-
Components and plugins
-
-
-

-

-

-

hwloc is organized in components that are responsible for discovering objects. Depending on the topology configuration, some components will be used, some will be ignored. The usual default is to enable the native operating system component, (e.g. linux or solaris) and the pci miscellaneous component. If available, an architecture-specific component (such as x86) may also improve the topology detection.

-

If a XML topology is loaded, the xml discovery component will be used instead of all other components. It internally uses a specific class of components for the actual XML import/export routines (xml_libxml and xml_nolibxml) but these will not be discussed here (see libxml2 and minimalistic XML backends).

-

-

-

-

-Components enabled by default

-

The hwloc core contains a list of components sorted by priority. Each one is enabled as long as it does not conflict with the previously enabled ones. This includes native operating system components, architecture-specific ones, and if available, I/O components such as pci.

-

Usually the native operating system component (when it exists, e.g. linux or aix) is enabled first. Then hwloc looks for an architecture specific component (e.g. x86). Finally there also exist a basic component (no_os) that just tries to discover the number of PUs in the system.

-

Each component discovers as much topology information as possible. Most of them, including most native OS components, do nothing unless the topology is still empty. Some others, such as x86 and pci, can complete and annotate what other backends found earlier. Discovery is performed by phases: CPUs are first discovered, then memory is attached, then PCI, etc.

-

Default priorities ensure that clever components are invoked first. Native operating system components have higher priorities, and are therefore invoked first, because they likely offer very detailed topology information. If needed, it will be later extended by architecture-specific information (e.g. from the x86 component).

-

If any configuration function such as hwloc_topology_set_xml() is used before loading the topology, the corresponding component is enabled first. Then, as usual, hwloc enables any other component (based on priorities) that does not conflict.

-

Certain components that manage a virtual topology, for instance XML topology import or synthetic topology description, conflict with all other components. Therefore, one of them may only be loaded (e.g. with hwloc_topology_set_xml()) if no other component is enabled.

-

The environment variable HWLOC_COMPONENTS_VERBOSE may be set to get verbose messages about component registration (including their priority) and enabling.

-

-

-

-

-Selecting which components to use

-

If no topology configuration functions such as hwloc_topology_set_synthetic() have been called, plugins may be selected with environment variables such as HWLOC_XMLFILE, HWLOC_SYNTHETIC, HWLOC_FSROOT, or HWLOC_CPUID_PATH (see Environment Variables).

-

Finally, the environment variable HWLOC_COMPONENTS resets the list of selected components. If the variable is set and empty (or set to a single comma separating nothing, since some operating systems do not accept empty variables), the normal plugin priority order is used.

-

If the variable is set to x86 in this variable will cause the x86 component to take precedence over any other component, including the native operating system component. It is therefore loaded first, before hwloc tries to load all remaining non-conflicting components. In this case, x86 would take care of discovering everything it supports, instead of only completing what the native OS information. This may be useful if the native component is buggy on some platforms.

-

It is possible to prevent some components from being loaded by prefixing their name with - in the list. For instance x86,-pci will load the x86 component, then let hwloc load all the usual components except pci. A single component phase may also be blacklisted, for instance with -linux:io. hwloc_topology_set_components() may also be used inside the program to prevent the loading of a specific component (or phases) for the target topology.

-

It is possible to prevent all remaining components from being loaded by placing stop in the environment variable. Only the components listed before this keyword will be enabled.

-

-

-

-

-Loading components from plugins

-

Components may optionally be built as plugins so that the hwloc core library does not directly depend on their dependencies (for instance the libpciaccess library). Plugin support may be enabled with the --enable-plugins configure option. All components buildable as plugins will then be built as plugins. The configure option may be given a comma-separated list of component names to specify the exact list of components to build as plugins.

-

Plugins are built as independent dynamic libraries that are installed in $libdir/hwloc. All plugins found in this directory are loaded during topology_init() (unless blacklisted in HWLOC_PLUGINS_BLACKLIST, see Environment Variables). A specific list of directories (colon-separated) to scan may be specified in the HWLOC_PLUGINS_PATH environment variable.

-

Note that loading a plugin just means that the corresponding component is registered to the hwloc core. Components are then only enabled if the topology configuration requests it, as explained in the previous sections.

-

Also note that plugins should carefully be enabled and used when embedding hwloc in another project, see Embedding hwloc in Other Software for details.

-

-

-

-

-Existing components and plugins

-

All components distributed within hwloc are listed below. The list of actually available components may be listed at running with the HWLOC_COMPONENTS_VERBOSE environment variable (see Environment Variables).

-
-
linux
-
The official component for discovering CPU, memory and I/O devices on Linux. It discovers PCI devices without the help of external libraries such as libpciaccess, but requires the pci component for adding vendor/device names to PCI objects. It also discovers many kinds of Linux-specific OS devices.
-
aix, darwin, freebsd, hpux, netbsd, solaris, windows
-
Each officially supported operating system has its own native component, which is statically built when supported, and which is used by default.
-
x86
-
The x86 architecture (either 32 or 64 bits) has its own component that may complete or replace the previously-found CPU information. It is statically built when supported.
-
bgq
-
This component is specific to IBM BlueGene/Q compute node (running CNK). It is built and enabled by default when --host=powerpc64-bgq-linux is passed to configure (see How do I build hwloc for BlueGene/Q?).
-
no_os
-
A basic component that just tries to detect the number of processing units in the system. It mostly serves on operating systems that are not natively supported. It is always statically built.
-
pci
-
PCI object discovery uses the external pciaccess library (aka libpciaccess); see I/O Devices. It may also annotate existing PCI devices with vendor and device names. It may be built as a plugin.
-
opencl
-
The OpenCL component creates co-processor OS device objects such as opencl0d0 (first device of the first OpenCL platform) or opencl1d3 (fourth device of the second platform). Only the AMD and NVIDIA OpenCL implementations currently offer locality information. It may be built as a plugin.
-
rsmi
-
This component creates GPU OS device objects such as rsmi0 for describing AMD GPUs. It may be built as a plugin.
-
levelzero
-
This component creates co-processor OS device objects such as ze0 for describing oneAPI Level Zero devices. It may also create sub-OS-devices such as ze0.0 inside those devices. It may be built as a plugin.
-
cuda
-
This component creates co-processor OS device objects such as cuda0 that correspond to NVIDIA GPUs used with CUDA library. It may be built as a plugin.
-
nvml
-
Probing the NVIDIA Management Library creates OS device objects such as nvml0 that are useful for batch schedulers. It also detects the actual PCIe link bandwidth without depending on power management state and without requiring administrator privileges. It may be built as a plugin.
-
gl
-
Probing the NV-CONTROL X extension (NVCtrl library) creates OS device objects such as :0.0 corresponding to NVIDIA displays. They are useful for graphical applications that need to place computation and/or data near a rendering GPU. It may be built as a plugin.
-
synthetic
-
Synthetic topology support (see Synthetic topologies) is always built statically.
-
xml
-
XML topology import (see Importing and exporting topologies from/to XML files) is always built statically. It internally uses one of the XML backends (see libxml2 and minimalistic XML backends).
    -
  • -xml_nolibxml is a basic and hwloc-specific XML import/export. It is always statically built.
    • -
  • -xml_libxml relies on the external libxml2 library for provinding a feature-complete XML import/export. It may be built as a plugin.
    • -
-
-
fake
-
A dummy plugin that does nothing but is used for debugging plugin support.
-
-
-
- - - - - - -
-
-
-
Embedding hwloc in Other Software
-
-
-

-

-

-

It can be desirable to include hwloc in a larger software package (be sure to check out the LICENSE file) so that users don't have to separately download and install it before installing your software. This can be advantageous to ensure that your software uses a known-tested/good version of hwloc, or for use on systems that do not have hwloc pre-installed.

-

When used in "embedded" mode, hwloc will:

-
    -
  • not install any header files
    • -
  • not build any documentation files
    • -
  • not build or install any executables or tests
    • -
  • not build libhwloc.* – instead, it will build libhwloc_embedded.*
    • -
-

There are two ways to put hwloc into "embedded" mode. The first is directly from the configure command line:

-
shell$ ./configure --enable-embedded-mode ...
-

The second requires that your software project uses the GNU Autoconf / Automake / Libtool tool chain to build your software. If you do this, you can directly integrate hwloc's m4 configure macro into your configure script. You can then invoke hwloc's configuration tests and build setup by calling a m4 macro (see below).

-

Although hwloc dynamic shared object plugins may be used in embedded mode, the embedder project will have to manually setup dlopen or libltdl in its build system so that hwloc can load its plugins at run time. Also, embedders should be aware of complications that can arise due to public and private linker namespaces (e.g., if the embedder project is loaded into a private namespace and then hwloc tries to dynamically load its plugins, such loading may fail since the hwloc plugins can't find the hwloc symbols they need). The embedder project is strongly advised not to use hwloc's dynamically loading plugins / dlopen / libltdl capability.

-

-

-

-

-Using hwloc's M4 Embedding Capabilities

-

Every project is different, and there are many different ways of integrating hwloc into yours. What follows is one example of how to do it.

-

If your project uses recent versions Autoconf, Automake, and Libtool to build, you can use hwloc's embedded m4 capabilities. We have tested the embedded m4 with projects that use Autoconf 2.65, Automake 1.11.1, and Libtool 2.2.6b. Slightly earlier versions of may also work but are untested. Autoconf versions prior to 2.65 are almost certain to not work.

-

You can either copy all the config/hwloc*m4 files from the hwloc source tree to the directory where your project's m4 files reside, or you can tell aclocal to find more m4 files in the embedded hwloc's "config" subdirectory (e.g., add "-Ipath/to/embedded/hwloc/config" to your Makefile.am's ACLOCAL_AMFLAGS).

-

The following macros can then be used from your configure script (only HWLOC_SETUP_CORE must be invoked if using the m4 macros):

-
    -

  • HWLOC_SETUP_CORE(config-dir-prefix, action-upon-success, action-upon-failure, print_banner_or_not): Invoke the hwloc configuration tests and setup the hwloc tree to build. The first argument is the prefix to use for AC_OUTPUT files – it's where the hwloc tree is located relative to $top_srcdir. Hence, if your embedded hwloc is located in the source tree at contrib/hwloc, you should pass [contrib/hwloc] as the first argument. If HWLOC_SETUP_CORE and the rest of configure completes successfully, then "make" traversals of the hwloc tree with standard Automake targets (all, clean, install, etc.) should behave as expected. For example, it is safe to list the hwloc directory in the SUBDIRS of a higher-level Makefile.am. The last argument, if not empty, will cause the macro to display an announcement banner that it is starting the hwloc core configuration tests.

    -

    HWLOC_SETUP_CORE will set the following environment variables and AC_SUBST them: HWLOC_EMBEDDED_CFLAGS, HWLOC_EMBEDDED_CPPFLAGS, and HWLOC_EMBEDDED_LIBS. These flags are filled with the values discovered in the hwloc-specific m4 tests, and can be used in your build process as relevant. The _CFLAGS, _CPPFLAGS, and _LIBS variables are necessary to build libhwloc (or libhwloc_embedded) itself.

    -

    HWLOC_SETUP_CORE also sets HWLOC_EMBEDDED_LDADD environment variable (and AC_SUBSTs it) to contain the location of the libhwloc_embedded.la convenience Libtool archive. It can be used in your build process to link an application or other library against the embedded hwloc library.

    -

    NOTE: If the HWLOC_SET_SYMBOL_PREFIX macro is used, it must be invoked before HWLOC_SETUP_CORE.

    -
    • -
  • HWLOC_BUILD_STANDALONE: HWLOC_SETUP_CORE defaults to building hwloc in an "embedded" mode (described above). If HWLOC_BUILD_STANDALONE is invoked *before* HWLOC_SETUP_CORE, the embedded definitions will not apply (e.g., libhwloc.la will be built, not libhwloc_embedded.la).
    • -
  • HWLOC_SET_SYMBOL_PREFIX(foo_): Tells the hwloc to prefix all of hwloc's types and public symbols with "foo_"; meaning that function hwloc_init() becomes foo_hwloc_init(). Enum values are prefixed with an upper-case translation if the prefix supplied; HWLOC_OBJ_CORE becomes FOO_hwloc_OBJ_CORE. This is recommended behavior if you are including hwloc in middleware – it is possible that your software will be combined with other software that links to another copy of hwloc. If both uses of hwloc utilize different symbol prefixes, there will be no type/symbol clashes, and everything will compile, link, and run successfully. If you both embed hwloc without changing the symbol prefix and also link against an external hwloc, you may get multiple symbol definitions when linking your final library or application.
    • -
  • HWLOC_SETUP_DOCS, HWLOC_SETUP_UTILS, HWLOC_SETUP_TESTS: These three macros only apply when hwloc is built in "standalone" mode (i.e., they should NOT be invoked unless HWLOC_BUILD_STANDALONE has already been invoked).
    • -
  • HWLOC_DO_AM_CONDITIONALS: If you embed hwloc in a larger project and build it conditionally with Automake (e.g., if HWLOC_SETUP_CORE is invoked conditionally), you must unconditionally invoke HWLOC_DO_AM_CONDITIONALS to avoid warnings from Automake (for the cases where hwloc is not selected to be built). This macro is necessary because hwloc uses some AM_CONDITIONALs to build itself, and AM_CONDITIONALs cannot be defined conditionally. Note that it is safe (but unnecessary) to call HWLOC_DO_AM_CONDITIONALS even if HWLOC_SETUP_CORE is invoked unconditionally. If you are not using Automake to build hwloc, this macro is unnecessary (and will actually cause errors because it invoked AM_* macros that will be undefined).
    • -
-

NOTE: When using the HWLOC_SETUP_CORE m4 macro, it may be necessary to explicitly invoke AC_CANONICAL_TARGET (which requires config.sub and config.guess) and/or AC_USE_SYSTEM_EXTENSIONS macros early in the configure script (e.g., after AC_INIT but before AM_INIT_AUTOMAKE). See the Autoconf documentation for further information.

-

Also note that hwloc's top-level configure.ac script uses exactly the macros described above to build hwloc in a standalone mode (by default). You may want to examine it for one example of how these macros are used.

-

-

-

-

-Example Embedding hwloc

-

Here's an example of integrating with a larger project named sandbox that already uses Autoconf, Automake, and Libtool to build itself:

-
# First, cd into the sandbox project source tree
-shell$ cd sandbox
-shell$ cp -r /somewhere/else/hwloc-<version> my-embedded-hwloc
-shell$ edit Makefile.am
-  1. Add "-Imy-embedded-hwloc/config" to ACLOCAL_AMFLAGS
-  2. Add "my-embedded-hwloc" to SUBDIRS
-  3. Add "$(HWLOC_EMBEDDED_LDADD)" and "$(HWLOC_EMBEDDED_LIBS)" to 
-     sandbox's executable's LDADD line.  The former is the name of the 
-     Libtool convenience library that hwloc will generate.  The latter 
-     is any dependent support libraries that may be needed by 
-     $(HWLOC_EMBEDDED_LDADD).
-  4. Add "$(HWLOC_EMBEDDED_CFLAGS)" to AM_CFLAGS
-  5. Add "$(HWLOC_EMBEDDED_CPPFLAGS)" to AM_CPPFLAGS
-shell$ edit configure.ac
-  1. Add "HWLOC_SET_SYMBOL_PREFIX(sandbox_hwloc_)" line
-  2. Add "HWLOC_SETUP_CORE([my-embedded-hwloc], [happy=yes], [happy=no])" line
-  3. Add error checking for happy=no case
-shell$ edit sandbox.c
-  1. Add #include <hwloc.h>
-  2. Add calls to sandbox_hwloc_init() and other hwloc API functions
-

Now you can bootstrap, configure, build, and run the sandbox as normal – all calls to "sandbox_hwloc_*" will use the embedded hwloc rather than any system-provided copy of hwloc.

-
-
- - - - - - -
-
-
-
Frequently Asked Questions (FAQ)
-
-
-

-

-

-

-Concepts

-

-I only need binding, why should I use hwloc ?

-

hwloc is its portable API that works on a variety of operating systems. It supports binding of threads, processes and memory buffers (see CPU binding and Memory binding). Even if some features are not supported on some systems, using hwloc is much easier than reimplementing your own portability layer.

-

Moreover, hwloc provides knowledge of cores and hardware threads. It offers easy ways to bind tasks to individual hardware threads, or to entire multithreaded cores, etc. See How may I ignore symmetric multithreading, hyper-threading, etc. in hwloc?. Most alternative software for binding do not even know whether each core is single-threaded, multithreaded or hyper-threaded. They would bind to individual threads without any way to know whether multiple tasks are in the same physical core.

-

However, using hwloc comes with an overhead since a topology must be loaded before gathering information and binding tasks or memory. Fortunately this overhead may be significantly reduced by filtering non-interesting information out of the topology.

-


- For instance, the default configuration is to keep all objects enabled (except I/Os and instruction caches). The following code tells hwloc to build a much smaller topology that only contains Cores (explicitly filtered-in below), hardware threads (PUs, cannot be filtered-out), NUMA nodes (cannot be filtered-out), and the root object (usually a Machine; the root cannot be removed without breaking the tree):

-
hwloc_topology_t topology;
-hwloc_topology_init(&topology);
-/* filter everything out */
-hwloc_topology_set_all_types_filter(topology, HWLOC_TYPE_FILTER_KEEP_NONE);
-/* filter Cores back in */
-hwloc_topology_set_type_filter(topology, HWLOC_OBJ_CORE, HWLOC_TYPE_FILTER_KEEP_ALL);
-hwloc_topology_load(topology);
-

However, one should remember that filtering such objects out removes locality information from the hwloc tree. For instance, we do not know anymore which PU is close to which NUMA node. This would be useful to applications that explicitly want to place specific memory buffers close to specific tasks. Those applications should also tell hwloc to keep Group objects that bring structure information: 

hwloc_topology_set_type_filter(topology, HWLOC_OBJ_GROUP, HWLOC_TYPE_FILTER_KEEP_STRUCTURE);
-


- Starting with hwloc 2.8, it is also possible to ignore distances between objects, memory performance attributes, and kinds of CPU cores, by setting topology flags before load: 

[...]
-/* disable distances, memory attributes and CPU kinds */
-hwloc_topology_set_flags(topology, HWLOC_TOPOLOGY_FLAG_NO_DISTANCES
-                                   |HWLOC_TOPOLOGY_FLAG_NO_MEMATTRS
-                                   |HWLOC_TOPOLOGY_FLAG_NO_CPUKINDS);
-[...]
-hwloc_topology_load(topology);
-

-Should I use logical or physical/OS indexes? and how?

-

One of the original reasons why hwloc was created is that physical/OS indexes (obj->os_index) are often crazy and unpredictable: processors numbers are usually non-contiguous (processors 0 and 1 are not physically close), they vary from one machine to another, and may even change after a BIOS or system update. This numbers make task placement hardly portable. Moreover some objects have no physical/OS numbers (caches), and some objects have non-unique numbers (core numbers are only unique within a socket). Physical/OS indexes are only guaranteed to exist and be unique for PU and NUMA nodes.

-

hwloc therefore introduces logical indexes (obj->logical_index) which are portable, contiguous and logically ordered (based on the resource organization in the locality tree). In general, one should only use logical indexes and just let hwloc do the internal conversion when really needed (when talking to the OS and hardware).

-

hwloc developers recommends that users do not use physical/OS indexes unless they really know what they are doing. The main reason for still using physical/OS indexes is when interacting with non-hwloc tools such as numactl or taskset, or when reading hardware information from raw sources such as /proc/cpuinfo.

-

lstopo options -l and -p may be used to switch between logical indexes (prefixed with L#) and physical/OS indexes (P#). Converting one into the other may also be achieved with hwloc-calc which may manipulate either logical or physical indexes as input or output. See also hwloc-calc.

-
# Convert PU with physical number 3 into logical number
-$ hwloc-calc -I pu --physical-input --logical-output pu:3
-5
-
-# Convert a set of NUMA nodes from logical to physical
-# (beware that the output order may not match the input order)
-$ hwloc-calc -I numa --logical-input --physical-output numa:2-3 numa:7
-0,2,5
-

-hwloc is only a structural model, it ignores performance models, memory bandwidth, etc.?

-

hwloc is indeed designed to provide applications with a structural model of the platform. This is an orthogonal approach to describing the machine with performance models, for instance using memory bandwidth or latencies measured by benchmarks. We believe that both approaches are important for helping application make the most of the hardware.

-

For instance, on a dual-processor host with four cores each, hwloc clearly shows which four cores are together. Latencies between all pairs of cores of the same processor are likely identical, and also likely lower than the latency between cores of different processors. However, the structural model cannot guarantee such implementation details. On the other side, performance models would reveal such details without always clearly identifying which cores are in the same processor.

-

The focus of hwloc is mainly of the structural modeling side. However, hwloc lets user adds performance information to the topology through distances (see Distances), memory attributes (see Memory Attributes) or even custom annotations (see How do I annotate the topology with private notes?). hwloc may also use such distance information for grouping objects together (see hwloc only has a one-dimensional view of the architecture, it ignores distances? and What are these Group objects in my topology?).

-

-hwloc only has a one-dimensional view of the architecture, it ignores distances?

-

hwloc places all objects in a tree. Each level is a one-dimensional view of a set of similar objects. All children of the same object (siblings) are assumed to be equally interconnected (same distance between any of them), while the distance between children of different objects (cousins) is supposed to be larger.

-

Modern machines exhibit complex hardware interconnects, so this tree may miss some information about the actual physical distances between objects. The hwloc topology may therefore be annotated with distance information that may be used to build a more realistic representation (multi-dimensional) of each level. For instance, there can be a distance matrix that representing the latencies between any pair of NUMA nodes if the BIOS and/or operating system reports them.

-

For more information about the hwloc distances, see Distances.

-

-What are these Group objects in my topology?

-

hwloc comes with a set of predefined object types (Core, Package, NUMA node, Caches) that match the vast majority of hardware platforms. The HWLOC_OBJ_GROUP type was designed for cases where this set is not sufficient. Groups may be used anywhere to add more structure information to the topology, for instance to show that 2 out of 4 NUMA nodes are actually closer than the others. When applicable, the subtype field describes why a Group was actually added (see also Normal attributes).

-

hwloc currently uses Groups for the following reasons:

    -
  • -NUMA parents when memory locality does not match any existing object.
    • -
  • -I/O parents when I/O locality does not match any existing object.
    • -
  • -Distance-based groups made of close objects.
    • -
  • -AMD Bulldozer dual-core compute units (subtype is ComputeUnit, in the x86 backend), but these objects are usually merged with the L2 caches.
    • -
  • -Intel Extended Topology Enumeration levels (in the x86 backend).
    • -
  • -Windows processor groups when HWLOC_WINDOWS_PROCESSOR_GROUP_OBJS=1 is set in the environment (except if they contain exactly a single NUMA node, or a single Package, etc.).
    • -
  • -IBM S/390 "Books" on Linux (subtype is Book).
    • -
  • -Linux Clusters of CPUs (subtype is Cluster), for instance for ARM cores sharing of some internal cache or bus, or x86 cores sharing a L2 cache (since Linux kernel 5.16). HWLOC_DONT_MERGE_CLUSTER_GROUPS=1 may be set in the environment to disable the automerging of these groups with identical caches, etc.
    • -
  • -AIX unknown hierarchy levels.
    • -
-

hwloc Groups are only kept if no other object has the same locality information. It means that a Group containing a single child is merged into that child. And a Group is merged into its parent if it is its only child. For instance a Windows processor group containing a single NUMA node would be merged with that NUMA node since it already contains the relevant hierarchy information.

-

When inserting a custom Group with hwloc_hwloc_topology_insert_group_object(), this merging may be disabled by setting its dont_merge attribute.

-

-What happens if my topology is asymmetric?

-

hwloc supports asymmetric topologies even if most platforms are usually symmetric. For example, there could be different types of processors in a single machine, each with different numbers of cores, symmetric multithreading, or levels of caches.

-

In practice, asymmetric topologies are rare but occur for at least two reasons:

    -
  • -Intermediate groups may added for I/O affinity: on a 4-package machine, an I/O bus may be connected to 2 packages. These packages are below an additional Group object, while the other packages are not (see also What are these Group objects in my topology?).
    • -
  • -If only part of a node is available to the current process, for instance because the resource manager uses Linux Cgroups to restrict process resources, some cores (or NUMA nodes) will disappear from the topology (unless flag HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED was passed). On a 32-core machine where 12 cores were allocated to the process, this may lead to one CPU package with 8 cores, another one with only 4 cores, and two missing packages.
    • -
-

To understand how hwloc manages such cases, one should first remember the meaning of levels and cousin objects. All objects of the same type are gathered as horizontal levels with a given depth. They are also connected through the cousin pointers of the hwloc_obj structure. Object attribute (cache depth and type, group depth) are also taken in account when gathering objects as horizontal levels. To be clear: there will be one level for L1i caches, another level for L1d caches, another one for L2, etc.

-

If the topology is asymmetric (e.g., if a group is missing above some processors), a given horizontal level will still exist if there exist any objects of that type. However, some branches of the overall tree may not have an object located in that horizontal level. Note that this specific hole within one horizontal level does not imply anything for other levels. All objects of the same type are gathered in horizontal levels even if their parents or children have different depths and types.

-

See the diagram in Terms and Definitions for a graphical representation of such topologies.

-

Moreover, it is important to understand that a same parent object may have children of different types (and therefore, different depths). These children are therefore siblings (because they have the same parent), but they are not cousins (because they do not belong to the same horizontal level).

-

-What happens to my topology if I disable symmetric multithreading, hyper-threading, etc. in the system?

-

hwloc creates one PU (processing unit) object per hardware thread. If your machine supports symmetric multithreading, for instance Hyper-Threading, each Core object may contain multiple PU objects: 

$ lstopo -
-...
-  Core L#0
-    PU L#0 (P#0)
-    PU L#1 (P#2)
-  Core L#1
-    PU L#2 (P#1)
-    PU L#3 (P#3)
-

x86 machines usually offer the ability to disable hyper-threading in the BIOS. Or it can be disabled on the Linux kernel command-line at boot time, or later by writing in sysfs virtual files.

-

If you do so, the hwloc topology structure does not significantly change, but some PU objects will not appear anymore. No level will disappear, you will see the same number of Core objects, but each of them will contain a single PU now. The PU level does not disappear either (remember that hwloc topologies always contain a PU level at the bottom of the topology) even if there is a single PU object per Core parent. 

$ lstopo -
-...
-  Core L#0
-    PU L#0 (P#0)
-  Core L#1
-    PU L#1 (P#1)
-

-How may I ignore symmetric multithreading, hyper-threading, etc. in hwloc?

-

First, see What happens to my topology if I disable symmetric multithreading, hyper-threading, etc. in the system? for more information about multithreading.

-

If you need to ignore symmetric multithreading in software, you should likely manipulate hwloc Core objects directly: 

/* get the number of cores */
-unsigned nbcores = hwloc_get_nbobjs_by_type(topology, HWLOC_OBJ_CORE);
-...
-/* get the third core below the first package */
-hwloc_obj_t package, core;
-package = hwloc_get_obj_by_type(topology, HWLOC_OBJ_PACKAGE, 0);
-core = hwloc_get_obj_inside_cpuset_by_type(topology, package->cpuset,
-                                           HWLOC_OBJ_CORE, 2);
-

Whenever you want to bind a process or thread to a core, make sure you singlify its cpuset first, so that the task is actually bound to a single thread within this core (to avoid useless migrations). 

/* bind on the second core */
-hwloc_obj_t core = hwloc_get_obj_by_type(topology, HWLOC_OBJ_CORE, 1);
-hwloc_cpuset_t set = hwloc_bitmap_dup(core->cpuset);
-hwloc_bitmap_singlify(set);
-hwloc_set_cpubind(topology, set, 0);
-hwloc_bitmap_free(set);
-

With hwloc-calc or hwloc-bind command-line tools, you may specify that you only want a single-thread within each core by asking for their first PU object: 

$ hwloc-calc core:4-7
-0x0000ff00
-$ hwloc-calc core:4-7.pu:0
-0x00005500
-

When binding a process on the command-line, you may either specify the exact thread that you want to use, or ask hwloc-bind to singlify the cpuset before binding 

$ hwloc-bind core:3.pu:0 -- echo "hello from first thread on core #3"
-hello from first thread on core #3
-...
-$ hwloc-bind core:3 --single -- echo "hello from a single thread on core #3"
-hello from a single thread on core #3
-

-

-

-

-Advanced

-

-I do not want hwloc to rediscover my enormous machine topology every time I rerun a process

-

Although the topology discovery is not expensive on common machines, its overhead may become significant when multiple processes repeat the discovery on large machines (for instance when starting one process per core in a parallel application). The machine topology usually does not vary much, except if some cores are stopped/restarted or if the administrator restrictions are modified. Thus rediscovering the whole topology again and again may look useless.

-

For this purpose, hwloc offers XML import/export and shared memory features.

-

XML lets you save the discovered topology to a file (for instance with the lstopo program) and reload it later by setting the HWLOC_XMLFILE environment variable. The HWLOC_THISSYSTEM environment variable should also be set to 1 to assert that loaded file is really the underlying system.

-

Loading a XML topology is usually much faster than querying multiple files or calling multiple functions of the operating system. It is also possible to manipulate such XML files with the C programming interface, and the import/export may also be directed to memory buffer (that may for instance be transmitted between applications through a package). See also Importing and exporting topologies from/to XML files.

-
Note
The environment variable HWLOC_THISSYSTEM_ALLOWED_RESOURCES may be used to load a XML topology that contains the entire machine and restrict it to the part that is actually available to the current process (e.g. when Linux Cgroup/Cpuset are used to restrict the set of resources). See Environment Variables.
-

Shared-memory topologies consist in one process exposing its topology in a shared-memory buffer so that other processes (running on the same machine) may use it directly. This has the advantage of reducing the memory footprint since a single topology is stored in physical memory for multiple processes. However, it requires all processes to map this shared-memory buffer at the same virtual address, which may be difficult in some cases. This API is described in Sharing topologies between processes.

-

-How many topologies may I use in my program?

-

hwloc lets you manipulate multiple topologies at the same time. However, these topologies consume memory and system resources (for instance file descriptors) until they are destroyed. It is therefore discouraged to open the same topology multiple times.

-

Sharing a single topology between threads is easy (see Thread Safety) since the vast majority of accesses are read-only.

-

If multiple topologies of different (but similar) nodes are needed in your program, have a look at How to avoid memory waste when manipulating multiple similar topologies?.

-

-How to avoid memory waste when manipulating multiple similar topologies?

-

hwloc does not share information between topologies. If multiple similar topologies are loaded in memory, for instance the topologies of different identical nodes of a cluster, lots of information will be duplicated.

-

hwloc/diff.h (see also Topology differences) offers the ability to compute topology differences, apply or unapply them, or export/import to/from XML. However, this feature is limited to basic differences such as attribute changes. It does not support complex modifications such as adding or removing some objects.

-

-How do I annotate the topology with private notes?

-

Each hwloc object contains a userdata field that may be used by applications to store private pointers. This field is only valid during the lifetime of these container object and topology. It becomes invalid as soon the topology is destroyed, or as soon as the object disappears, for instance when restricting the topology. The userdata field is not exported/imported to/from XML by default since hwloc does not know what it contains. This behavior may be changed by specifying application-specific callbacks with hwloc_topology_set_userdata_export_callback() and hwloc_topology_set_userdata_import_callback().

-

Each object may also contain some info attributes (key name and value) that are setup by hwloc during discovery and that may be extended by the user with hwloc_obj_add_info() (see also Object attributes). Contrary to the userdata field which is unique, multiple info attributes may exist for each object, even with the same name. These attributes are always exported to XML. However, only character strings may be used as key names and values.

-

It is also possible to insert Misc objects with a custom name anywhere as a leaf of the topology (see Miscellaneous objects). And Misc objects may have their own userdata and info attributes just like any other object.

-

The hwloc-annotate command-line tool may be used for adding Misc objects and info attributes.

-

There is also a topology-specific userdata pointer that can be used to recognize different topologies by storing a custom pointer. It may be manipulated with hwloc_topology_set_userdata() and hwloc_topology_get_userdata().

-

-How do I create a custom heterogeneous and asymmetric topology?

-

Synthetic topologies (see Synthetic topologies) allow to create custom topologies but they are always symmetric: same numbers of cores in each package, same local NUMA nodes, same shared cache, etc. To create an asymmetric topology, for instance to simulate hybrid CPUs, one may want to start from a larger symmetric topology and restrict it.
-

-

Assuming we want two packages, one with 4 dual-threaded cores, and one with 8 single-threaded cores, first we create a topology with two identical packages, each with 8 dual-threaded cores: 

$ lstopo -i "pack:2 core:8 pu:2" topo.xml
-

Then create the bitmask representing the PUs that we wish to keep and pass it to lstopo's restrict option: 

$ hwloc-calc -i topo.xml pack:0.core:0-3.pu:0-1 pack:1.core:0-7.pu:0
-0x555500ff
-$ lstopo -i topo.xml --restrict 0x555500ff topo2.xml
-$ mv -f topo2.xml topo.xml
-

To mark the cores of first package as Big (power hungry) and those of second package as Little (energy efficient), define CPU kinds: 

$ hwloc-annotate topo.xml topo.xml -- none -- cpukind $(hwloc-calc -i topo.xml pack:0) 1 0 CoreType Big
-$ hwloc-annotate topo.xml topo.xml -- none -- cpukind $(hwloc-calc -i topo.xml pack:1) 0 0 CoreType Little
-


-

-

A similar method may be used for heterogeneous memory. First we specify 2 NUMA nodes per package in our synthetic description: 

$ lstopo -i "pack:2 [numa(memory=100GB)] [numa(memory=10GB)] core:8 pu:2" topo.xml
-

Then remove the second node of first package: 

$ hwloc-calc -i topo.xml --nodeset node:all ~pack:0.node:1
-0x0000000e
-$ lstopo -i topo.xml --restrict nodeset=0xe topo2.xml
-$ mv -f topo2.xml topo.xml
-

Then make one large node even bigger: 

$ hwloc-annotate topo.xml topo.xml -- pack:0.numa:0 -- size 200GB
-

Now we have 200GB in first package, and 100GB+10GB in second package.
-

-

Next we may specify that the small NUMA node (second of second package) is HBM while the large ones are DRAM: 

$ hwloc-annotate topo.xml topo.xml -- pack:0.numa:0 pack:1.numa:0 -- subtype DRAM
-$ hwloc-annotate topo.xml topo.xml -- pack:1.numa:1 -- subtype HBM
-

Finally we may define memory performance attributes to specify that the HBM bandwidth (200GB/s) from local cores is higher than the DRAM bandwidth (50GB/s): 

$ hwloc-annotate topo.xml topo.xml -- pack:0.numa:0 -- memattr Bandwidth pack:0 50000
-$ hwloc-annotate topo.xml topo.xml -- pack:1.numa:0 -- memattr Bandwidth pack:1 50000
-$ hwloc-annotate topo.xml topo.xml -- pack:1.numa:1 -- memattr Bandwidth pack:1 200000
-


-

-

There is currently no way to create or modify I/O devices attached to such fake topologies. There is also no way to have some partial levels, e.g. a L3 cache in one package but not in the other.
-

-

More changes may obviously be performed by manually modifying the XML export file. Simple operations such as modifying object attributes (cache size, memory size info keypairs, etc.), moving I/O subtrees, moving Misc objects, or removing objects are easy to perform.

-

However, modifying CPU and Memory objects requires care since cpusets and nodesets are supposed to remain consistent between parents and children. Similarly, PCI bus IDs should remain consistent between bridges and children within an I/O subtree.

-

-

-

-

-Caveats

-

-Why is hwloc slow?

-

Building a hwloc topology on a large machine may be slow because the discovery of hundreds of hardware cores or threads takes time (especially when reading thousands of sysfs files on Linux). Ignoring some objects (for instance caches) that aren't useful to the current application may improve this overhead (see I only need binding, why should I use hwloc ?). One should also consider using XML (see I do not want hwloc to rediscover my enormous machine topology every time I rerun a process) to work around such issues.

-

Additionally, lstopo enables most hwloc objects and discovery flags by default so that the output topology is as precise as possible (while hwloc disables many of them by default). This includes I/O device discovery through PCI libraries as well as external libraries such as NVML. To speed up lstopo, you may disable such features with command-line options such as --no-io.

-

When NVIDIA GPU probing is enabled with CUDA or NVML, one should make sure that the Persistent mode is enabled (with nvidia-smi -pm 1) to avoid significant GPU initialization overhead.

-

When AMD GPU discovery is enabled with OpenCL and hwloc is used remotely over ssh, some spurious round-trips on the network may significantly increase the discovery time. Forcing the DISPLAY environment variable to the remote X server display (usually :0) instead of only setting the COMPUTE variable may avoid this.

-

Also remember that these components may be disabled at build-time with configure flags such as --disable-opencl, --disable-cuda or --disable-nvml, and at runtime with the environment variable HWLOC_COMPONENTS=-opencl,-cuda,-nvml or with hwloc_topology_set_components().

-

-Does hwloc require privileged access?

-

hwloc discovers the topology by querying the operating system. Some minor features may require privileged access to the operation system. For instance memory module discovery on Linux is reserved to root, and the entire PCI discovery on Solaris and BSDs requires access to some special files that are usually restricted to root (/dev/pci* or /devices/pci*).

-

To workaround this limitation, it is recommended to export the topology as a XML file generated by the administrator (with the lstopo program) and make it available to all users (see Importing and exporting topologies from/to XML files). It will offer all discovery information to any application without requiring any privileged access anymore. Only the necessary hardware characteristics will be exported, no sensitive information will be disclosed through this XML export.

-

This XML-based model also has the advantage of speeding up the discovery because reading a XML topology is usually much faster than querying the operating system again.

-

The utility hwloc-dump-hwdata is also involved in gathering privileged information at boot time and making it available to non-privileged users (note that this may require a specific SELinux MLS policy module). However, it only applies to Intel Xeon Phi processors for now (see Why do I need hwloc-dump-hwdata for memory on Intel Xeon Phi processor?). See also HWLOC_DUMPED_HWDATA_DIR in Environment Variables for details about the location of dumped files.

-

-What should I do when hwloc reports "operating system" warnings?

-

When the operating system reports invalid locality information (because of either software or hardware bugs), hwloc may fail to insert some objects in the topology because they cannot fit in the already built tree of resources. If so, hwloc will report a warning like the following. The object causing this error is ignored, the discovery continues but the resulting topology will miss some objects and may be asymmetric (see also What happens if my topology is asymmetric?).

-
****************************************************************************
-* hwloc received invalid information from the operating system.
-*
-* L3 (cpuset 0x000003f0) intersects with NUMANode (P#0 cpuset 0x0000003f) without inclusion!
-* Error occurred in topology.c line 940
-*
-* Please report this error message to the hwloc user's mailing list,
-* along with the files generated by the hwloc-gather-topology script.
-*
-* hwloc will now ignore this invalid topology information and continue.
-****************************************************************************
-

These errors are common on large AMD platforms because of BIOS and/or Linux kernel bugs causing invalid L3 cache information. In the above example, the hardware reports a L3 cache that is shared by 2 cores in the first NUMA node and 4 cores in the second NUMA node. That's wrong, it should actually be shared by all 6 cores in a single NUMA node. The resulting topology will miss some L3 caches.

-

If your application does not care about cache sharing, or if you do not plan to request cache-aware binding in your process launcher, you may likely ignore this error (and hide it by setting HWLOC_HIDE_ERRORS=1 in your environment).

-

Some platforms report similar warnings about conflicting Packages and NUMANodes.

-

On x86 hosts, passing HWLOC_COMPONENTS=x86 in the environment may workaround some of these issues by switching to a different way to discover the topology.

-

Upgrading the BIOS and/or the operating system may help. Otherwise, as explained in the message, reporting this issue to the hwloc developers (by sending the tarball that is generated by the hwloc-gather-topology script on this platform) is a good way to make sure that this is a software (operating system) or hardware bug (BIOS, etc).

-

See also Questions and Bugs. Opening an issue on GitHub automatically displays hints on what information you should provide when reporting such bugs.

-

-Why does Valgrind complain about hwloc memory leaks?

-

If you are debugging your application with Valgrind, you want to avoid memory leak reports that are caused by hwloc and not by your program.

-

hwloc itself is often checked with Valgrind to make sure it does not leak memory. However, some global variables in hwloc dependencies are never freed. For instance libz allocates its global state once at startup and never frees it so that it may be reused later. Some libxml2 global state is also never freed because hwloc does not know whether it can safely ask libxml2 to free it (the application may also be using libxml2 outside of hwloc).

-

These unfreed variables cause leak reports in Valgrind. hwloc installs a Valgrind suppressions file to hide them. You should pass the following command-line option to Valgrind to use it: 

  --suppressions=/path/to/hwloc-valgrind.supp
-

-

-

-

-Platform-specific

-

-How do I enable ROCm SMI and select which version to use?

-

hwloc enables ROCm SMI as soon as it finds its development headers and libraries on the system. This detection consists in looking in /opt/rocm by default. If a ROCm version was specified with --with-rocm-version=4.4.0 or in the ROCM_VERSION environment variable, then /opt/rocm-<version> is used instead. Finally, a specific installation path may be specified with --with-rocm=/path/to/rocm.

-

As usual, developer header and library paths may also be set through environment variables such as LIBRARY_PATH and C_INCLUDE_PATH.

-

To find out whether ROCm SMI was detected and enabled, look in Probe / display I/O devices at the end of the configure script output. Passing --enable-rsmi will also cause configure to fail if RSMI could not be found and enabled in hwloc.

-

-How do I enable CUDA and select which CUDA version to use?

-

hwloc enables CUDA as soon as it finds CUDA development headers and libraries on the system. This detection may be performed thanks to pkg-config but it requires hwloc to know which CUDA version to look for. This may be done by passing --with-cuda-version=11.0 to the configure script. Otherwise hwloc will also look for the CUDA_VERSION environment variable.

-

If pkg-config does not work, passing --with-cuda=/path/to/cuda to the configure script is another way to define the corresponding library and header paths. Finally, these paths may also be set through environment variables such as LIBRARY_PATH and C_INCLUDE_PATH.

-

These paths, either detected by pkg-config or given manually, will also be used to detect NVML and OpenCL libraries and enable their hwloc backends.

-

To find out whether CUDA was detected and enabled, look in Probe / display I/O devices at the end of the configure script output. Passing --enable-cuda will also cause configure to fail if CUDA could not be found and enabled in hwloc.

-

Note that --with-cuda=/nonexisting may be used to disable all dependencies that are installed by CUDA, i.e. the CUDA, NVML and NVIDIA OpenCL backends, since the given directory does not exist.

-

-How do I find the local MCDRAM NUMA node on Intel Xeon Phi processor?

-

Intel Xeon Phi processors introduced a new memory architecture by possibly having two distinct local memories: some normal memory (DDR) and some high-bandwidth on-package memory (MCDRAM). Processors can be configured in various clustering modes to have up to 4 Clusters. Moreover, each Cluster (quarter, half or whole processor) of the processor may have its own local parts of the DDR and of the MCDRAM. This memory and clustering configuration may be probed by looking at MemoryMode and ClusterMode attributes, see Hardware Platform Information and doc/examples/get-knl-modes.c in the source directory.

-

Starting with version 2.0, hwloc properly exposes this memory configuration. DDR and MCDRAM are attached as two memory children of the same parent, DDR first, and MCDRAM second if any. Depending on the processor configuration, that parent may be a Package, a Cache, or a Group object of type Cluster.

-

Hence cores may have one or two local NUMA nodes, listed by the core nodeset. An application may allocate local memory from a core by using that nodeset. The operating system will actually allocate from the DDR when possible, or fallback to the MCDRAM.

-

To allocate specifically on one of these memories, one should walk up the parent pointers until finding an object with some memory children. Looking at these memory children will give the DDR first, then the MCDRAM if any. Their nodeset may then be used for allocating or binding memory buffers.

-

One may also traverse the list of NUMA nodes until finding some whose cpuset matches the target core or PUs. The MCDRAM NUMA nodes may be identified thanks to the subtype field which is set to MCDRAM.

-

Command-line tools such as hwloc-bind may bind memory on the MCDRAM by using the hbm keyword. For instance, to bind on the first MCDRAM NUMA node:

-
$ hwloc-bind --membind --hbm numa:0 -- myprogram
-$ hwloc-bind --membind numa:0 -- myprogram
-

-Why do I need hwloc-dump-hwdata for memory on Intel Xeon Phi processor?

-

Intel Xeon Phi processors may use the on-package memory (MCDRAM) as either memory or a memory-side cache (reported as a L3 cache by hwloc by default, see HWLOC_KNL_MSCACHE_L3 in Environment Variables). There are also several clustering modes that significantly affect the memory organization (see How do I find the local MCDRAM NUMA node on Intel Xeon Phi processor? for more information about these modes). Details about these are currently only available to privileged users. Without them, hwloc relies on a heuristic for guessing the modes.

-

The hwloc-dump-hwdata utility may be used to dump this privileged binary information into human-readable and world-accessible files that the hwloc library will later load. The utility should usually run as root once during boot, in order to update dumped information (stored under /var/run/hwloc by default) in case the MCDRAM or clustering configuration changed between reboots.

-

When SELinux MLS policy is enabled, a specific hwloc policy module may be required so that all users get access to the dumped files (in /var/run/hwloc by default). One may use hwloc policy files from the SELinux Reference Policy at https://github.com/TresysTechnology/refpolicy-contrib (see also the documentation at https://github.com/TresysTechnology/refpolicy/wiki/GettingStarted).

-

hwloc-dump-hwdata requires dmi-sysfs kernel module loaded.

-

The utility is currently unneeded on platforms without Intel Xeon Phi processors.

-

See HWLOC_DUMPED_HWDATA_DIR in Environment Variables for details about the location of dumped files.

-

-How do I build hwloc for BlueGene/Q?

-

IBM BlueGene/Q machines run a standard Linux on the login/frontend nodes and a custom CNK (Compute Node Kernel) on the compute nodes.

-

To discover the topology of a login/frontend node, hwloc should be configured as usual, without any BlueGene/Q-specific option.

-

However, one would likely rather discover the topology of the compute nodes where parallel jobs are actually running. If so, hwloc must be cross-compiled with the following configuration line: 

./configure --host=powerpc64-bgq-linux --disable-shared --enable-static \
-  CPPFLAGS='-I/bgsys/drivers/ppcfloor -I/bgsys/drivers/ppcfloor/spi/include/kernel/cnk/'
-

CPPFLAGS may have to be updated if your platform headers are installed in a different directory.

-

-How do I build hwloc for Windows?

-

hwloc binary releases for Windows are available on the website download pages (as pre-built ZIPs for both 32bits and 64bits x86 platforms). However hwloc also offers several ways to build on Windows:

-
    -
  • -The usual Unix build steps (configure, make and make install) work on the MSYS2/MinGW environment on Windows (the official hwloc binary releases are built this way). Some environment variables and options must be configured, see contrib/ci.inria.fr/job-3-mingw.sh in the hwloc repository for an example (used for nightly testing).
    • -
  • -hwloc also supports such Unix-like builds in Cygwin (environment for porting Unix code to Windows).
    • -
  • -Windows build is also possible with CMake (CMakeLists.txt available under contrib/windows-cmake/).
    • -
  • -hwloc also comes with an example of Microsoft Visual Studio solution (under contrib/windows/) that may serve as a base for custom builds.
    • -
-

-How to get useful topology information on NetBSD?

-

The NetBSD (and FreeBSD) backend uses x86-specific topology discovery (through the x86 component). This implementation requires CPU binding so as to query topology information from each individual processor. This means that hwloc cannot find any useful topology information unless user-level process binding is allowed by the NetBSD kernel. The security.models.extensions.user_set_cpu_affinity sysctl variable must be set to 1 to do so. Otherwise, only the number of processors will be detected.

-

-Why does binding fail on AIX?

-

The AIX operating system requires specific user capabilities for attaching processes to resource sets (CAP_NUMA_ATTACH). Otherwise functions such as hwloc_set_cpubind() fail (return -1 with errno set to EPERM).

-

This capability must also be inherited (through the additional CAP_PROPAGATE capability) if you plan to bind a process before forking another process, for instance with hwloc-bind.

-

These capabilities may be given by the administrator with: 

chuser "capabilities=CAP_PROPAGATE,CAP_NUMA_ATTACH" <username>
-

-

-

-

-Compatibility between hwloc versions

-

-How do I handle API changes?

-

The hwloc interface is extended with every new major release. Any application using the hwloc API should be prepared to check at compile-time whether some features are available in the currently installed hwloc distribution.

-

For instance, to check whether the hwloc version is at least 2.0, you should use: 

#include <hwloc.h>
-#if HWLOC_API_VERSION >= 0x00020000
-...
-#endif
-

To check for the API of release X.Y.Z at build time, you may compare HWLOC_API_VERSION with (X<<16)+(Y<<8)+Z.

-

For supporting older releases that do not have HWLOC_OBJ_NUMANODE and HWLOC_OBJ_PACKAGE yet, you may use:

-
#include <hwloc.h>
-#if HWLOC_API_VERSION < 0x00010b00
-#define HWLOC_OBJ_NUMANODE HWLOC_OBJ_NODE
-#define HWLOC_OBJ_PACKAGE HWLOC_OBJ_SOCKET
-#endif
-

Once a program is built against a hwloc library, it may also dynamically link with compatible libraries from other hwloc releases. The version of that runtime library may be queried with hwloc_get_api_version(). See How do I handle ABI breaks? for using this function for testing ABI compatibility.

-

-What is the difference between API and library version numbers?

-

HWLOC_API_VERSION is the version of the API. It changes when functions are added, modified, etc. However it does not necessarily change from one release to another. For instance, two releases of the same series (e.g. 2.0.3 and 2.0.4) usually have the same HWLOC_API_VERSION (0x00020000). However their HWLOC_VERSION strings are different ("2.0.3" and "2.0.4" respectively).

-

-How do I handle ABI breaks?

-

The hwloc interface was deeply modified in release 2.0 to fix several issues of the 1.x interface (see Upgrading to the hwloc 2.0 API and the NEWS file in the source directory for details). The ABI was broken, which means applications must be recompiled against the new 2.0 interface.

-

To check that you are not mixing old/recent headers with a recent/old runtime library, check the major revision number in the API version: 

#include <hwloc.h>
-  unsigned version = hwloc_get_api_version();
-  if ((version >> 16) != (HWLOC_API_VERSION >> 16)) {
-    fprintf(stderr,
-           "%s compiled for hwloc API 0x%x but running on library API 0x%x.\n"
-           "You may need to point LD_LIBRARY_PATH to the right hwloc library.\n"
-           "Aborting since the new ABI is not backward compatible.\n",
-           callname, HWLOC_API_VERSION, version);
-    exit(EXIT_FAILURE);
-  }
-

To specifically detect v2.0 issues: 

#include <hwloc.h>
-#if HWLOC_API_VERSION >= 0x00020000
-  /* headers are recent */
-  if (hwloc_get_api_version() < 0x20000)
-    ... error out, the hwloc runtime library is older than 2.0 ...
-#else
-  /* headers are pre-2.0 */
-  if (hwloc_get_api_version() >= 0x20000)
-    ... error out, the hwloc runtime library is more recent than 2.0 ...
-#endif
-

In theory, library sonames prevent linking with incompatible libraries. However custom hwloc installations or improperly configured build environments may still lead to such issues. Hence running one of the above (cheap) checks before initializing hwloc topology may be useful.

-

-Are XML topology files compatible between hwloc releases?

-

XML topology files are forward-compatible: a XML file may be loaded by a hwloc library that is more recent than the hwloc release that exported that file.

-

However, hwloc XMLs are not always backward-compatible: Topologies exported by hwloc 2.x cannot be imported by 1.x by default (see XML changes for working around such issues). There are also some corner cases where backward compatibility is not guaranteed because of changes between major releases (for instance 1.11 XMLs could not be imported in 1.10).

-

XMLs are exchanged at runtime between some components of the HPC software stack (for instance the resource managers and MPI processes). Building all these components on the same (cluster-wide) hwloc installation is a good way to avoid such incompatibilities.

-

-Are synthetic strings compatible between hwloc releases?

-

Synthetic strings (see Synthetic topologies) are forward-compatible: a synthetic string generated by a release may be imported by future hwloc libraries.

-

However they are often not backward-compatible because new details may have been added to synthetic descriptions in recent releases. Some flags may be given to hwloc_topology_export_synthetic() to avoid such details and stay backward compatible.

-

-Is it possible to share a shared-memory topology between different hwloc releases?

-

Shared-memory topologies (see Sharing topologies between processes) have strong requirements on compatibility between hwloc libraries. Adopting a shared-memory topology fails if it was exported by a non-compatible hwloc release. Releases with same major revision are usually compatible (e.g. hwloc 2.0.4 may adopt a topology exported by 2.0.3) but different major revisions may be incompatible (e.g. hwloc 2.1.0 cannot adopt from 2.0.x).

-

Topologies are shared at runtime between some components of the HPC software stack (for instance the resource managers and MPI processes). Building all these components on the same (system-wide) hwloc installation is a good way to avoid such incompatibilities.

-
-
- - - - - - -
-
-
-
Upgrading to the hwloc 2.0 API
-
-
-

-

-

-

See Compatibility between hwloc versions for detecting the hwloc version that you are compiling and/or running against.

-

-

-

-

-New Organization of NUMA nodes and Memory

-

-Memory children

-

In hwloc v1.x, NUMA nodes were inside the tree, for instance Packages contained 2 NUMA nodes which contained a L3 and several cache.

-

Starting with hwloc v2.0, NUMA nodes are not in the main tree anymore. They are attached under objects as Memory Children on the side of normal children. This memory children list starts at obj->memory_first_child and its size is obj->memory_arity. Hence there can now exist two local NUMA nodes, for instance on Intel Xeon Phi processors.

-

The normal list of children (starting at obj->first_child, ending at obj->last_child, of size obj->arity, and available as the array obj->children) now only contains CPU-side objects: PUs, Cores, Packages, Caches, Groups, Machine and System. hwloc_get_next_child() may still be used to iterate over all children of all lists.

-

Hence the CPU-side hierarchy is built using normal children, while memory is attached to that hierarchy depending on its affinity.

-

-Examples

-
    -
  • -

    a UMA machine with 2 packages and a single NUMA node is now modeled as a "Machine" object with two "Package" children and one "NUMANode" memory children (displayed first in lstopo below): 

    Machine (1024MB total)
-  NUMANode L#0 (P#0 1024MB)
-  Package L#0
-    Core L#0 + PU L#0 (P#0)
-    Core L#1 + PU L#1 (P#1)
-  Package L#1
-    Core L#2 + PU L#2 (P#2)
-    Core L#3 + PU L#3 (P#3)
-

    -
    • -
  • -

    a machine with 2 packages with one NUMA node and 2 cores in each is now: 

    Machine (2048MB total)
-  Package L#0
-    NUMANode L#0 (P#0 1024MB)
-    Core L#0 + PU L#0 (P#0)
-    Core L#1 + PU L#1 (P#1)
-  Package L#1
-    NUMANode L#1 (P#1 1024MB)
-    Core L#2 + PU L#2 (P#2)
-    Core L#3 + PU L#3 (P#3)
-

    -
    • -
  • -

    if there are two NUMA nodes per package, a Group object may be added to keep cores together with their local NUMA node: 

    Machine (4096MB total)
-  Package L#0
-    Group0 L#0
-      NUMANode L#0 (P#0 1024MB)
-      Core L#0 + PU L#0 (P#0)
-      Core L#1 + PU L#1 (P#1)
-    Group0 L#1
-      NUMANode L#1 (P#1 1024MB)
-      Core L#2 + PU L#2 (P#2)
-      Core L#3 + PU L#3 (P#3)
-  Package L#1
-    [...]
-

    -
    • -
  • -if the platform has L3 caches whose localities are identical to NUMA nodes, Groups aren't needed: 
    Machine (4096MB total)
-  Package L#0
-    L3 L#0 (16MB)
-      NUMANode L#0 (P#0 1024MB)
-      Core L#0 + PU L#0 (P#0)
-      Core L#1 + PU L#1 (P#1)
-    L3 L#1 (16MB)
-      NUMANode L#1 (P#1 1024MB)
-      Core L#2 + PU L#2 (P#2)
-      Core L#3 + PU L#3 (P#3)
-  Package L#1
-    [...]
-
    • -
-

-NUMA level and depth

-

NUMA nodes are not in "main" tree of normal objects anymore. Hence, they don't have a meaningful depth anymore (like I/O and Misc objects). They have a virtual (negative) depth (HWLOC_TYPE_DEPTH_NUMANODE) so that functions manipulating depths and level still work, and so that we can still iterate over the level of NUMA nodes just like for any other level.

-

For instance we can still use lines such as 

int depth = hwloc_get_type_depth(topology, HWLOC_OBJ_NUMANODE);
-hwloc_obj_t obj = hwloc_get_obj_by_type(topology, HWLOC_OBJ_NUMANODE, 4);
-hwloc_obj_t node = hwloc_get_next_obj_by_depth(topology, HWLOC_TYPE_DEPTH_NUMANODE, prev);
-

The NUMA depth should not be compared with others. An unmodified code that still compares NUMA and Package depths (to find out whether Packages contain NUMA or the contrary) would now always assume Packages contain NUMA (because the NUMA depth is negative).

-

However, the depth of the Normal parents of NUMA nodes may be used instead. In the last example above, NUMA nodes are attached to L3 caches, hence one may compare the depth of Packages and L3 to find out that NUMA nodes are contained in Packages. This depth of parents may be retrieved with hwloc_get_memory_parents_depth(). However, this function may return HWLOC_TYPE_DEPTH_MULTIPLE on future platforms if NUMA nodes are attached to different levels.

-

-Finding Local NUMA nodes and looking at Children and Parents

-

Applications that walked up/down to find NUMANode parent/children must now be updated. Instead of looking directly for a NUMA node, one should now look for an object that has some memory children. NUMA node(s) will be attached there. For instance, when looking for a NUMA node above a given core core: 

hwloc_obj_t parent = core->parent;
-while (parent && !parent->memory_arity)
-  parent = parent->parent; /* no memory child, walk up */
-if (parent)
-  /* use parent->memory_first_child (and its siblings if there are multiple local NUMA nodes) */
-

The list of local NUMA nodes (usually a single one) is also described by the nodeset attribute of each object (which contains the physical indexes of these nodes). Iterating over the NUMA level is also an easy way to find local NUMA nodes: 

hwloc_obj_t tmp = NULL;
-while ((tmp = hwloc_get_next_obj_by_type(topology, HWLOC_OBJ_NUMANODE, tmp)) != NULL) {
-  if (hwloc_bitmap_isset(obj->nodeset, tmp->os_index))
-    /* tmp is a NUMA node local to obj, use it */
-}
-

Similarly finding objects that are close to a given NUMA nodes should be updated too. Instead of looking at the NUMA node parents/children, one should now find a Normal parent above that NUMA node, and then look at its parents/children as usual: 

hwloc_obj_t tmp = obj->parent;
-while (hwloc_obj_type_is_memory(tmp))
-  tmp = tmp->parent;
-/* now use tmp instead of obj */
-

To avoid such hwloc v2.x-specific and NUMA-specific cases in the code, a generic lookup for any kind of object, including NUMA nodes, might also be implemented by iterating over a level. For instance finding an object of type type which either contains or is included in object obj can be performed by traversing the level of that type and comparing CPU sets: 

hwloc_obj_t tmp = NULL;
-while ((tmp = hwloc_get_next_obj_by_type(topology, type, tmp)) != NULL) {
-  if (hwloc_bitmap_intersects(tmp->cpuset, obj->cpuset))
-    /* tmp matches, use it */
-}
-

This generic lookup works whenever type or obj are Normal or Memory objects since both have CPU sets. Moreover, it is compatible with the hwloc v1.x API.

-

-

-

-

-4 Kinds of Objects and Children

-

-I/O and Misc children

-

I/O children are not in the main object children list anymore either. They are in the list starting at obj->io_first_child and its size is obj->io_arity.

-

Misc children are not in the main object children list anymore. They are in the list starting at obj->misc_first_child and its size is obj->misc_arity.

-

See hwloc_obj for details about children lists.

-

hwloc_get_next_child() may still be used to iterate over all children of all lists.

-

-Kinds of objects

-

Given the above, objects may now be of 4 kinds:

    -
  • -Normal (everything not listed below, including Machine, Package, Core, PU, CPU Caches, etc);
    • -
  • -Memory (currently NUMA nodes or Memory-side Caches), attached to parents as Memory children;
    • -
  • -I/O (Bridges, PCI and OS devices), attached to parents as I/O children;
    • -
  • -Misc objects, attached to parents as Misc children.
    • -
-

See hwloc_obj for details about children lists.

-

For a given object type, the kind may be found with hwloc_obj_type_is_normal(), hwloc_obj_type_is_memory(), hwloc_obj_type_is_normal(), or comparing with HWLOC_OBJ_MISC.

-

Normal and Memory objects have (non-NULL) CPU sets and nodesets, while I/O and Misc objects don't have any sets (they are NULL).

-

-

-

-

-HWLOC_OBJ_CACHE replaced

-

Instead of a single HWLOC_OBJ_CACHE, there are now 8 types HWLOC_OBJ_L1CACHE, ..., HWLOC_OBJ_L5CACHE, HWLOC_OBJ_L1ICACHE, ..., HWLOC_OBJ_L3ICACHE.

-

Cache object attributes are unchanged.

-

hwloc_get_cache_type_depth() is not needed to disambiguate cache types anymore since new types can be passed to hwloc_get_type_depth() without ever getting HWLOC_TYPE_DEPTH_MULTIPLE anymore.

-

hwloc_obj_type_is_cache(), hwloc_obj_type_is_dcache() and hwloc_obj_type_is_icache() may be used to check whether a given type is a cache, data/unified cache or instruction cache.

-

-

-

-

-allowed_cpuset and allowed_nodeset only in the main topology

-

Objects do not have allowed_cpuset and allowed_nodeset anymore. They are only available for the entire topology using hwloc_topology_get_allowed_cpuset() and hwloc_topology_get_allowed_nodeset().

-

As usual, those are only needed when the INCLUDE_DISALLOWED topology flag is given, which means disallowed objects are kept in the topology. If so, one may find out whether some PUs inside an object is allowed by checking 

hwloc_bitmap_intersects(obj->cpuset, hwloc_topology_get_allowed_cpuset(topology))
-

Replace cpusets with nodesets for NUMA nodes. To find out which ones, replace intersects() with and() to get the actual intersection.

-

-

-

-

-Object depths are now signed int

-

obj->depth as well as depths given to functions such as hwloc_get_obj_by_depth() or returned by hwloc_topology_get_depth() are now signed int.

-

Other depth such as cache-specific depth attribute are still unsigned.

-

-

-

-

-Memory attributes become NUMANode-specific

-

Memory attributes such as obj->memory.local_memory are now only available in NUMANode-specific attributes in obj->attr->numanode.local_memory.

-

obj->memory.total_memory is available in all objects as obj->total_memory.

-

See hwloc_obj_attr_u::hwloc_numanode_attr_s and hwloc_obj for details.

-

-

-

-

-Topology configuration changes

-

The old ignoring API as well as several configuration flags are replaced with the new filtering API, see hwloc_topology_set_type_filter() and its variants, and hwloc_type_filter_e for details.

-
    -
  • -

    hwloc_topology_ignore_type(), hwloc_topology_ignore_type_keep_structure() and hwloc_topology_ignore_all_keep_structure() are respectively superseded by 

    hwloc_topology_set_type_filter(topology, type, HWLOC_TYPE_FILTER_KEEP_NONE);
-hwloc_topology_set_type_filter(topology, type, HWLOC_TYPE_FILTER_KEEP_STRUCTURE);
-hwloc_topology_set_all_types_filter(topology, HWLOC_TYPE_FILTER_KEEP_STRUCTURE);
-

    Also, the meaning of KEEP_STRUCTURE has changed (only entire levels may be ignored, instead of single objects), the old behavior is not available anymore.

    -

    -
    • -
  • -

    HWLOC_TOPOLOGY_FLAG_ICACHES is superseded by 

    hwloc_topology_set_icache_types_filter(topology, HWLOC_TYPE_FILTER_KEEP_ALL);
-

    -
    • -
  • -

    HWLOC_TOPOLOGY_FLAG_WHOLE_IO, HWLOC_TOPOLOGY_FLAG_IO_DEVICES and HWLOC_TOPOLOGY_FLAG_IO_BRIDGES replaced.

    -

    To keep all I/O devices (PCI, Bridges, and OS devices), use: 

    hwloc_topology_set_io_types_filter(topology, HWLOC_TYPE_FILTER_KEEP_ALL);
-

    To only keep important devices (Bridges with children, common PCI devices and OS devices): 

    hwloc_topology_set_io_types_filter(topology, HWLOC_TYPE_FILTER_KEEP_IMPORTANT);
-

    -
    • -
-

-

-

-

-XML changes

-

2.0 XML files are not compatible with 1.x

-

2.0 can load 1.x files, but only NUMA distances are imported. Other distance matrices are ignored (they were never used by default anyway).

-

2.0 can export 1.x-compatible files, but only distances attached to the root object are exported (i.e. distances that cover the entire machine). Other distance matrices are dropped (they were never used by default anyway).

-

Users are advised to negociate hwloc versions between exporter and importer: If the importer isn't 2.x, the exporter should export to 1.x. Otherwise, things should work by default.

-

Hence hwloc_topology_export_xml() and hwloc_topology_export_xmlbuffer() have a new flags argument. to force a hwloc-1.x-compatible XML export.

    -
  • -If both always support 2.0, don't pass any flag.
    • -
  • -When the importer uses hwloc 1.x, export with HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1. Otherwise the importer will fail to import.
    • -
  • -When the exporter uses hwloc 1.x, it cannot pass any flag, and a 2.0 importer can import without problem.
    • -
-
#if HWLOC_API_VERSION >= 0x20000
-   if (need 1.x compatible XML export)
-      hwloc_topology_export_xml(...., HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1);
-   else /* need 2.x compatible XML export */
-      hwloc_topology_export_xml(...., 0);
-#else
-   hwloc_topology_export_xml(....);
-#endif
-

Additionally, hwloc_topology_diff_load_xml(), hwloc_topology_diff_load_xmlbuffer(), hwloc_topology_diff_export_xml(), hwloc_topology_diff_export_xmlbuffer() and hwloc_topology_diff_destroy() lost the topology argument: The first argument (topology) isn't needed anymore.

-

-

-

-

-Distances API totally rewritten

-

The new distances API is in hwloc/distances.h.

-

Distances are not accessible directly from objects anymore. One should first call hwloc_distances_get() (or a variant) to retrieve distances (possibly with one call to get the number of available distances structures, and another call to actually get them). Then it may consult these structures, and finally release them.

-

The set of object involved in a distances structure is specified by an array of objects, it may not always cover the entire machine or so.

-

-

-

-

-Return values of functions

-

Bitmap functions (and a couple other functions) can return errors (in theory).

-

Most bitmap functions may have to reallocate the internal bitmap storage. In v1.x, they would silently crash if realloc failed. In v2.0, they now return an int that can be negative on error. However, the preallocated storage is 512 bits, hence realloc will not even be used unless you run hwloc on machines with larger PU or NUMAnode indexes.

-

hwloc_obj_add_info(), hwloc_cpuset_from_nodeset() and hwloc_cpuset_from_nodeset() also return an int, which would be -1 in case of allocation errors.

-

-

-

-

-Misc API changes

- -

-

-

-

-API removals and deprecations

-
    -
  • -

    HWLOC_OBJ_SYSTEM removed: The root object is always HWLOC_OBJ_MACHINE

    -

    -
    • -
  • -

    _membind_nodeset() memory binding interfaces deprecated: One should use the variant without _nodeset suffix and pass the HWLOC_MEMBIND_BYNODESET flag.

    -

    -
    • -
  • -

    HWLOC_MEMBIND_REPLICATE removed: no supported operating system supports it anymore.

    -

    -
    • -
  • -

    hwloc_obj_snprintf() removed because it was long-deprecated by hwloc_obj_type_snprintf() and hwloc_obj_attr_snprintf().

    -

    -
    • -
  • -

    hwloc_obj_type_sscanf() deprecated, hwloc_obj_type_of_string() removed.

    -

    -
    • -
  • -

    hwloc_cpuset_from/to_nodeset_strict() deprecated: Now useless since all topologies are NUMA. Use the variant without the _strict suffix

    -

    -
    • -
  • -

    hwloc_distribute() and hwloc_distributev() removed, deprecated by hwloc_distrib().

    -

    -
    • -
  • -

    The Custom interface (hwloc_topology_set_custom(), etc.) was removed, as well as the corresponding command-line tools (hwloc-assembler, etc.). Topologies always start with object with valid cpusets and nodesets.

    -

    -
    • -
  • -

    obj->online_cpuset removed: Offline PUs are simply listed in the complete_cpuset as previously.

    -

    -
    • -
  • -

    obj->os_level removed.

    -

    -
    • -
-
-
- - - - - - -
-
-
-
Network Locality (netloc)
-
-
-

-

-

-

Portable abstraction of network topologies for high-performance computing.

-

The netloc documentation spans of these sections:

-

-

-

-

-Netloc Summary

-

The Portable Network Locality (netloc) software package provides network topology discovery tools, and an abstract representation of those networks topologies for a range of network types and configurations. It is provided as a companion to the Portable Hardware Locality (hwloc) package. These two software packages work together to provide a comprehensive view of the HPC system topology, spanning from the processor cores in one server to the cores in another - including the complex network(s) in between.

-

Towards this end, netloc is divided into two sets of components. The first tools are for the admin to extract the information about the topology of the machines with topology discovery tools for each network type and discovery technique (called readers). The second set of tools is for the user to exploit the collected information: to display the topology or create a topology-aware mapping of the processes of an application.

-
- -
-

-

-

-

-Supported Networks

-

For now, only InfiniBand (See Setup) is supported, but it is planned to be extended it very soon.

-

-

-

-

-Netloc Installation

-

The generic installation procedure for both hwloc and netloc is described in Installation.

-

Note that netloc is currently not supported on as many platforms as the original hwloc project. netloc is enabled by default when supported, or can be disabled by passing --disable-netloc to the configure command-line.

-

-

-

-

-Setup

-

To use Netloc tools, we need two steps. The first step consists in getting information about network directly from tools distributed by manufacturers. For Infiniband, for instance, this operation needs privileges to access to the network device. For this step we have wrappers in Netloc that will call the right tools with the right options.

-

The second step will transform the raw files generated by manufacturer tools, into files in a format readable by Netloc tools, and that will not depend on network technologies.

-

To be clear, let's take an example with Infiniband. This first step is handled by netloc_ib_gather_raw that will call ibnetdiscover and ibroutes tools to generate the necessary raw data files. The step has to be run by an administrator, since the Infiniband tools need to access to the network device.

-
shell$ netloc_ib_gather_raw --help
-Usage: netloc_ib_gather_raw [options] <outdir>
-  Dumps topology information to <outdir>/ib-raw/
-  Subnets are guessed from the <outdir>/hwloc/ directory where
-  the hwloc XML exports of some nodes are stored.
-Options:
- --sudo
-    Pass sudo to internal ibnetdiscover and ibroute invocations.
-    Useful when the entire script cannot run as root.
- --hwloc-dir <dir>
-    Use <dir> instead of <outdir>/hwloc/ for hwloc XML exports.
- --force-subnet [<subnet>:]<board>:<port> to force the discovery
-    Do not guess subnets from hwloc XML exports.
-    Force discovery on local board <board> port <port>
-    and optionally force the subnet id <subnet>
-    instead of reading it from the first GID.
-    Examples: --force-subnet mlx4_0:1
-              --force-subnet fe80:0000:0000:0000:mlx4_0:1
- --ibnetdiscover /path/to/ibnetdiscover
- --ibroute /path/to/ibroute
-    Specify exact location of programs. Default is /usr/bin/<program>
- --sleep <n>
-    Sleep for <n> seconds between invocations of programs probing the network
- --ignore-errors
-    Ignore errors from ibnetdiscover and ibroute, assume their outputs are ok
- --force -f
-    Always rediscover to overwrite existing files without asking
- --verbose -v
-    Add verbose messages
- --dry-run
-    Do not actually run programs or modify anything
- --help -h
-    Show this help
-
-shell$ ./netloc_ib_gather_raw /home/netloc/data
-WARNING: Not running as root.
-Using /home/netloc/data/hwloc as hwloc lstopo XML directory.
-
-Exporting local node hwloc XML...
-  Running lstopo-no-graphics...
-
-Found 1 subnets in hwloc directory:
- Subnet fe80:0000:0000:0000 is locally accessible from board qib0 port 1.
-
-Looking at fe80:0000:0000:0000 (through local board qib0 port 1)...
- Running ibnetdiscover...
- Getting routes...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L112' LID 18...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L108' LID 20...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L102' LID 23...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L104' LID 25...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L106' LID 24...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L114' LID 22...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L116' LID 21...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L109' LID 12...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L111' LID 11...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L107' LID 13...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L103' LID 17...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L105' LID 16...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L113' LID 15...
-

The second step, that can be done by a regular user, is done by the tool netloc_ib_extract_dats.

-
shell$ netloc_ib_extract_dats --help
-Usage: netloc_ib_extract_dats <path to input raw data files> <output path> [--hwloc-dir
-<hwloc xml path>]
-        hwloc-dir can be an absolute path or a relative path from output path
-
-shell$ netloc_ib_extract_dats /home/netloc/data/ib-raw /home/netloc/data/netloc \
-  --hwloc-dir ../hwloc
-Read subnet: fe80:0000:0000:0000
-2 partitions found
-        'node'
-        'admin'
-

-

-

-

-Topology display

-

Netloc provides a tool, netloc_draw.html, that displays a topology in a web browser, by using a JSON file.

-

-Generate the JSON file

-

In order to display a topology, Netloc needs to generate a JSON file corresponding to a topology. For this operation, the user must run netloc_draw_to_json.

-
shell$ netloc_draw_to_json --help
-Usage: netloc_draw_to_json <path to topology directory>
-
-shell$ netloc_draw_to_json /home/netloc/data/netloc
-

The netloc_draw_to_json command will write a JSON file for each topology file found in the input directory. The output files, written also in the input directory, can be open by netloc_draw.html in a web browser.

-

-Using netloc_draw

-

Once the JSON file is opened, the rendering is generated by the Javascript vis library for computing the position of the nodes. From the interface, it is possible to search for a specific node, to color the nodes, to expand merged switches, to show statistics, to export as an image... The user can interact with the nodes by moving them. For now, there are bugs and other nodes might move too.

-

The placement of the nodes is done statically if the topology is detected as a tree. If not, vis.js will use physics to find good positions, and it can be very time consuming.

-
- -
-
-
- - - - - - -
-
-
-
Netloc with Scotch
-
-
-

-

-

-

Scotch is a toolbox for graph partitioning [XXX], that can do mapping between a communication graph and an architecture. Netloc interfaces with Scotch, by getting the topology of the machine and building the Scotch architecture. It is also possible to directly build a mapping file that can be given to mpirun.

-

-

-

-

-Introduction

-

Scotch is able to deal architectures to represent the topology of a complete machine. Scotch handles several types of topologies: complete graphs, hypercubes, fat trees, meshes, torus, and random graphs. Moreover, Scotch is able to manage parts of architectures that are called sub-architectures. Thus, from a complete architecture, we can create a sub-architecture that will represent the available resources of the complete machine.

-

-

-

-

-Setup

-

The first step in order to use Netloc tools is to discover the network. For this task, we provide tools called netloc_gather that are wrappers to the dedicated tools provided by the manufacturer of the network, that generate the raw data given by the devices. This task needs privileges to access to the network devices. Once, this task is completed, the raw data is converted in a generic format independent to the fabric by extract_dats. Figure 1 shows how the different modules of Netloc are linked, and what are the tools provided by Netloc.

-

-

-

-

-Tools and API

-

When the machine is discovered and all the needed files are generated as seen previously, a user can call the netlocscotch functions from the API and interact with Scotch.

-

-Build Scotch architectures

-

Netloc provides a function to export the built topology into the Scotch format. That will give the possibility to the user to play with the topology in Scotch. Since Netloc matches the discovered topology with known topologies, the Scotch architecture won’t be random graphs but known topologies also in Scotch that will lead to optimized graph algorithms. This function is called netlocscotch_build_arch.

-

When the network topology is a tree, the topology converted by netlocscotch is the complete topology of the machine containing intranode topologies from hwloc. In this case, merging the two levels results in a bigger tree. For other network topologies, the global graph created for Scotch is a generic graph since it not not (at this moment) possible to create nested known architectures.

-

-Build Scotch sub-architectures

-

Most of the time, the user does not have access to the complete machine. He uses a resource manager to run his application and he will gain access only to a set of nodes. In this case getting the Scotch architecture of the complete machine is not relevant. Fortunately, Netloc is also able to build a Scotch sub-architecture that will contain only the available nodes. For this operation the user needs to run a specific program, netloc_get_resources, that will record in a file, the lists of available nodes and available cores by using MPI and hwloc. From this file, the function netlocscotch_build_subarch will build the Scotch sub-architecture.

-

-Mapping of processes

-

A main goal in having all these data about the network topology, especially in Scotch structures, is to help the process placement. For that, we use the mapping of a process graph to the architecture provided by Scotch. As we have seen previously, Netloc is able to detect the structure of the topology and will build the adapted Scotch architecture that will be more efficient than a random structure.

-

In case, the network topology is not a tree, netlocscotch converts the complete topology into a generic graph. The drawback in that is the Scotch graph algorithms are less efficient. To overcome that, netlocscotch does two steps of mapping: first it maps the processes to the nodes, and then for each node maps the processes to the cores. We have to conduct tests to check if the method gives better results than using a generic graph directly.

-

The other input needed in Scotch is the process graph. Since we want to optimize the placement to decrease the communication time, a good metric for building the application graph is the amount of communications between all pairs of processes. Studies still have to be done to choose, in the most efficient way, what we take into account to define the amount of communications between the number of messages, the size of messages... This information will be transformed into a process graph.

-

Once we have a good mapping computed by Scotch, we can give it to the user, or Netloc can even generate the corresponding rank file useful to MPI.

-
-
- - - - - - -
-
-
-
Data Structures
-
-
-
Here are the data structures with brief descriptions:
-
[detail level 123]
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 Chwloc_backendDiscovery backend structure
 Chwloc_cl_device_topology_amd
 Chwloc_componentGeneric component structure
 Chwloc_disc_componentDiscovery component structure
 Chwloc_disc_statusDiscovery status structure
 Chwloc_distances_sMatrix of distances between a set of objects
 Chwloc_info_sObject info
 ▼Chwloc_locationWhere to measure attributes from
 Chwloc_location_uActual location
 Chwloc_objStructure of a topology object
 ▼Chwloc_obj_attr_uObject type-specific Attributes
 Chwloc_bridge_attr_sBridge specific Object Attributes
 Chwloc_cache_attr_sCache-specific Object Attributes
 Chwloc_group_attr_sGroup-specific Object Attributes
 ▼Chwloc_numanode_attr_sNUMA node-specific Object Attributes
 Chwloc_memory_page_type_sArray of local memory page types, NULL if no local memory and page_types is 0
 Chwloc_osdev_attr_sOS Device specific Object Attributes
 Chwloc_pcidev_attr_sPCI Device specific Object Attributes
 Chwloc_topology_cpubind_supportFlags describing actual PU binding support for this topology
 ▼Chwloc_topology_diff_obj_attr_uOne object attribute difference
 Chwloc_topology_diff_obj_attr_generic_s
 Chwloc_topology_diff_obj_attr_string_sString attribute modification with an optional name
 Chwloc_topology_diff_obj_attr_uint64_sInteger attribute modification with an optional index
 ▼Chwloc_topology_diff_uOne element of a difference list between two topologies
 Chwloc_topology_diff_generic_s
 Chwloc_topology_diff_obj_attr_s
 Chwloc_topology_diff_too_complex_s
 Chwloc_topology_discovery_supportFlags describing actual discovery support for this topology
 Chwloc_topology_membind_supportFlags describing actual memory binding support for this topology
 Chwloc_topology_misc_supportFlags describing miscellaneous features
 Chwloc_topology_supportSet of flags describing actual support for this topology
-
-
- - - - - - - -
-
-
Data Structure Index
-
-
-
H
-
-
-
H
-
hwloc_backend
hwloc_obj_attr_u::hwloc_bridge_attr_s
hwloc_obj_attr_u::hwloc_cache_attr_s
hwloc_cl_device_topology_amd
hwloc_component
hwloc_disc_component
hwloc_disc_status
hwloc_distances_s
hwloc_obj_attr_u::hwloc_group_attr_s
hwloc_info_s
hwloc_location
hwloc_location::hwloc_location_u
hwloc_obj_attr_u::hwloc_numanode_attr_s::hwloc_memory_page_type_s
hwloc_obj_attr_u::hwloc_numanode_attr_s
hwloc_obj
hwloc_obj_attr_u
hwloc_obj_attr_u::hwloc_osdev_attr_s
hwloc_obj_attr_u::hwloc_pcidev_attr_s
hwloc_topology_cpubind_support
hwloc_topology_diff_u::hwloc_topology_diff_generic_s
hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_generic_s
hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s
hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s
hwloc_topology_diff_obj_attr_u
hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s
hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s
hwloc_topology_diff_u
hwloc_topology_discovery_support
hwloc_topology_membind_support
hwloc_topology_misc_support
hwloc_topology_support
-
-
- - - - - - - - -
-
-
hwloc Directory Reference
-
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

-Files

file  bitmap.h [code]
 
file  cpukinds.h [code]
 
file  cuda.h [code]
 
file  cudart.h [code]
 
file  diff.h [code]
 
file  distances.h [code]
 
file  export.h [code]
 
file  gl.h [code]
 
file  glibc-sched.h [code]
 
file  helper.h [code]
 
file  levelzero.h [code]
 
file  linux-libnuma.h [code]
 
file  linux.h [code]
 
file  memattrs.h [code]
 
file  nvml.h [code]
 
file  opencl.h [code]
 
file  openfabrics-verbs.h [code]
 
file  plugins.h [code]
 
file  rsmi.h [code]
 
file  shmem.h [code]
 
file  windows.h [code]
 
-
- - - - - - - - -
-
-
include Directory Reference
-
-
- - - - -

-Directories

directory  hwloc
 
- - - - - -

-Files

file  hwloc.h [code]
 
file  netloc.h [code]
 
-
- - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/projects/hwloc/doc/v2.9.0/dudley.png b/projects/hwloc/doc/v2.9.0/dudley.png deleted file mode 100644 index d0f955a60..000000000 Binary files a/projects/hwloc/doc/v2.9.0/dudley.png and /dev/null differ diff --git a/projects/hwloc/doc/v2.9.0/dynsections.js b/projects/hwloc/doc/v2.9.0/dynsections.js deleted file mode 100644 index 3174bd7be..000000000 --- a/projects/hwloc/doc/v2.9.0/dynsections.js +++ /dev/null @@ -1,121 +0,0 @@ -/* - @licstart The following is the entire license notice for the JavaScript code in this file. - - The MIT License (MIT) - - Copyright (C) 1997-2020 by Dimitri van Heesch - - Permission is hereby granted, free of charge, to any person obtaining a copy of this software - and associated documentation files (the "Software"), to deal in the Software without restriction, - including without limitation the rights to use, copy, modify, merge, publish, distribute, - sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is - furnished to do so, subject to the following conditions: - - The above copyright notice and this permission notice shall be included in all copies or - substantial portions of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING - BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND - NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, - DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - - @licend The above is the entire license notice for the JavaScript code in this file - */ -function toggleVisibility(linkObj) -{ - var base = $(linkObj).attr('id'); - var summary = $('#'+base+'-summary'); - var content = $('#'+base+'-content'); - var trigger = $('#'+base+'-trigger'); - var src=$(trigger).attr('src'); - if (content.is(':visible')===true) { - content.hide(); - summary.show(); - $(linkObj).addClass('closed').removeClass('opened'); - $(trigger).attr('src',src.substring(0,src.length-8)+'closed.png'); - } else { - content.show(); - summary.hide(); - $(linkObj).removeClass('closed').addClass('opened'); - $(trigger).attr('src',src.substring(0,src.length-10)+'open.png'); - } - return false; -} - -function updateStripes() -{ - $('table.directory tr'). - removeClass('even').filter(':visible:even').addClass('even'); -} - -function toggleLevel(level) -{ - $('table.directory tr').each(function() { - var l = this.id.split('_').length-1; - var i = $('#img'+this.id.substring(3)); - var a = $('#arr'+this.id.substring(3)); - if (l - - - - - - -
-
Here is a list of all struct and union fields with links to the structures/unions they belong to:
- -

- a -

- - -

- b -

- - -

- c -

- - -

- d -

- - -

- e -

- - -

- f -

- - -

- g -

- - -

- i -

- - -

- k -

- - -

- l -

- - -

- m -

- - -

- n -

- - -

- o -

- - -

- p -

- - -

- r -

- - -

- s -

- - -

- t -

- - -

- u -

- - -

- v -

-
- - - - - - - -
-  - -

- a -

- - -

- b -

- - -

- c -

- - -

- d -

- - -

- e -

- - -

- f -

- - -

- g -

- - -

- i -

- - -

- k -

- - -

- l -

- - -

- m -

- - -

- n -

- - -

- o -

- - -

- p -

- - -

- r -

- - -

- s -

- - -

- t -

- - -

- u -

- - -

- v -

-
- - - - - - - -
-
-
Hardware Locality
-
-
-

Portable abstraction of parallel architectures for high-performance computing

-
-

-

-

-

-Introduction

-

The Hardware Locality (hwloc) software project aims at easing the process of discovering hardware resources in parallel architectures. It offers command-line tools and a C API for consulting these resources, their locality, attributes, and interconnection. hwloc primarily aims at helping high-performance computing (HPC) applications, but is also applicable to any project seeking to exploit code and/or data locality on modern computing platforms.

-

hwloc is actually made of two subprojects distributed together:

-

-See also the Related pages tab above for links to other sections. -

-

Netloc may be disabled, but the original hwloc cannot. Both hwloc and netloc APIs are documented after these sections.

-

-

-

-

-Installation

-

hwloc (https://www.open-mpi.org/projects/hwloc/) is available under the BSD license. It is hosted as a sub-project of the overall Open MPI project (https://www.open-mpi.org/). Note that hwloc does not require any functionality from Open MPI – it is a wholly separate (and much smaller!) project and code base. It just happens to be hosted as part of the overall Open MPI project.

-

-Basic Installation

-

Installation is the fairly common GNU-based process:

-
shell$ ./configure --prefix=...
-shell$ make
-shell$ make install
-

hwloc- and netloc-specific configure options and requirements are documented in sections hwloc Installation and Netloc Installation respectively.

-

Also note that if you install supplemental libraries in non-standard locations, hwloc's configure script may not be able to find them without some help. You may need to specify additional CPPFLAGS, LDFLAGS, or PKG_CONFIG_PATH values on the configure command line.

-

For example, if libpciaccess was installed into /opt/pciaccess, hwloc's configure script may not find it be default. Try adding PKG_CONFIG_PATH to the ./configure command line, like this:

-
./configure PKG_CONFIG_PATH=/opt/pciaccess/lib/pkgconfig ...
-

Running the "lstopo" tool is a good way to check as a graphical output whether hwloc properly detected the architecture of your node. Netloc command-line tools can be used to display the network topology interconnecting your nodes.

-

-Installing from a Git clone

-

Additionally, the code can be directly cloned from Git:

-
shell$ git clone https://github.com/open-mpi/hwloc.git
-shell$ cd hwloc
-shell$ ./autogen.sh
-

Note that GNU Autoconf >=2.63, Automake >=1.11 and Libtool >=2.2.6 are required when building from a Git clone.

-

Nightly development snapshots are available on the web site, they can be configured and built without any need for Git or GNU Autotools.

-

-

-

-

-Questions and Bugs

-

Bugs should be reported in the tracker (https://github.com/open-mpi/hwloc/issues). Opening a new issue automatically displays lots of hints about how to debug and report issues.

-

Questions may be sent to the users or developers mailing lists (https://www.open-mpi.org/community/lists/hwloc.php).

-

There is also a #hwloc IRC channel on Libera Chat (irc.libera.chat).

-
-
-'; - for (var i in data.children) { - result+='
  • '+ - data.children[i].text+''+ - makeTree(data.children[i],relPath)+'
    • '; - } - result+=''; - } - return result; - } - - $('#main-nav').append(makeTree(menudata,relPath)); - $('#main-nav').children(':first').addClass('sm sm-dox').attr('id','main-menu'); - if (searchEnabled) { - if (serverSide) { - $('#main-menu').append('
    • '); - } else { - $('#main-menu').append('
    • '); - } - } - $('#main-menu').smartmenus(); -} -/* @license-end */ diff --git a/projects/hwloc/doc/v2.9.0/menudata.js b/projects/hwloc/doc/v2.9.0/menudata.js deleted file mode 100644 index 7dc9262eb..000000000 --- a/projects/hwloc/doc/v2.9.0/menudata.js +++ /dev/null @@ -1,71 +0,0 @@ -/* - @licstart The following is the entire license notice for the JavaScript code in this file. - - The MIT License (MIT) - - Copyright (C) 1997-2020 by Dimitri van Heesch - - Permission is hereby granted, free of charge, to any person obtaining a copy of this software - and associated documentation files (the "Software"), to deal in the Software without restriction, - including without limitation the rights to use, copy, modify, merge, publish, distribute, - sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is - furnished to do so, subject to the following conditions: - - The above copyright notice and this permission notice shall be included in all copies or - substantial portions of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING - BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND - NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, - DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - - @licend The above is the entire license notice for the JavaScript code in this file -*/ -var menudata={children:[ -{text:"Main Page",url:"index.php"}, -{text:"Related Pages",url:"pages.php"}, -{text:"Modules",url:"modules.php"}, -{text:"Data Structures",url:"annotated.php",children:[ -{text:"Data Structures",url:"annotated.php"}, -{text:"Data Fields",url:"functions.php",children:[ -{text:"All",url:"functions.php",children:[ -{text:"a",url:"functions.php#index_a"}, -{text:"b",url:"functions.php#index_b"}, -{text:"c",url:"functions.php#index_c"}, -{text:"d",url:"functions.php#index_d"}, -{text:"e",url:"functions.php#index_e"}, -{text:"f",url:"functions.php#index_f"}, -{text:"g",url:"functions.php#index_g"}, -{text:"i",url:"functions.php#index_i"}, -{text:"k",url:"functions.php#index_k"}, -{text:"l",url:"functions.php#index_l"}, -{text:"m",url:"functions.php#index_m"}, -{text:"n",url:"functions.php#index_n"}, -{text:"o",url:"functions.php#index_o"}, -{text:"p",url:"functions.php#index_p"}, -{text:"r",url:"functions.php#index_r"}, -{text:"s",url:"functions.php#index_s"}, -{text:"t",url:"functions.php#index_t"}, -{text:"u",url:"functions.php#index_u"}, -{text:"v",url:"functions.php#index_v"}]}, -{text:"Variables",url:"functions_vars.php",children:[ -{text:"a",url:"functions_vars.php#index_a"}, -{text:"b",url:"functions_vars.php#index_b"}, -{text:"c",url:"functions_vars.php#index_c"}, -{text:"d",url:"functions_vars.php#index_d"}, -{text:"e",url:"functions_vars.php#index_e"}, -{text:"f",url:"functions_vars.php#index_f"}, -{text:"g",url:"functions_vars.php#index_g"}, -{text:"i",url:"functions_vars.php#index_i"}, -{text:"k",url:"functions_vars.php#index_k"}, -{text:"l",url:"functions_vars.php#index_l"}, -{text:"m",url:"functions_vars.php#index_m"}, -{text:"n",url:"functions_vars.php#index_n"}, -{text:"o",url:"functions_vars.php#index_o"}, -{text:"p",url:"functions_vars.php#index_p"}, -{text:"r",url:"functions_vars.php#index_r"}, -{text:"s",url:"functions_vars.php#index_s"}, -{text:"t",url:"functions_vars.php#index_t"}, -{text:"u",url:"functions_vars.php#index_u"}, -{text:"v",url:"functions_vars.php#index_v"}]}]}]}]} diff --git a/projects/hwloc/doc/v2.9.0/modules.php b/projects/hwloc/doc/v2.9.0/modules.php deleted file mode 100644 index 89f3951f8..000000000 --- a/projects/hwloc/doc/v2.9.0/modules.php +++ /dev/null @@ -1,92 +0,0 @@ - - - - - - -
    -
    -
    -
    Modules
    -
    -
    -
    Here is a list of all modules:
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     API version
     Object Sets (hwloc_cpuset_t and hwloc_nodeset_t)
     Object Types
     Object Structure and Attributes
     Topology Creation and Destruction
     Object levels, depths and types
     Converting between Object Types and Attributes, and Strings
     Consulting and Adding Key-Value Info Attributes
     CPU binding
     Memory binding
     Changing the Source of Topology Discovery
     Topology Detection Configuration and Query
     Modifying a loaded Topology
     Finding Objects inside a CPU set
     Finding Objects covering at least CPU set
     Looking at Ancestor and Child Objects
     Kinds of object Type
     Looking at Cache Objects
     Finding objects, miscellaneous helpers
     Distributing items over a topology
     CPU and node sets of entire topologies
     Converting between CPU sets and node sets
     Finding I/O objects
     The bitmap API
     Exporting Topologies to XML
     Exporting Topologies to Synthetic
     Retrieve distances between objects
     Helpers for consulting distance matrices
     Add distances between objects
     Remove distances between objects
     Comparing memory node attributes for finding where to allocate on
     Managing memory attributes
     Kinds of CPU cores
     Linux-specific helpers
     Interoperability with Linux libnuma unsigned long masks
     Interoperability with Linux libnuma bitmask
     Windows-specific helpers
     Interoperability with glibc sched affinity
     Interoperability with OpenCL
     Interoperability with the CUDA Driver API
     Interoperability with the CUDA Runtime API
     Interoperability with the NVIDIA Management Library
     Interoperability with the ROCm SMI Management Library
     Interoperability with the oneAPI Level Zero interface.
     Interoperability with OpenGL displays
     Interoperability with OpenFabrics
     Topology differences
     Sharing topologies between processes
     Components and Plugins: Discovery components
     Components and Plugins: Discovery backends
     Components and Plugins: Generic components
     Components and Plugins: Core functions to be used by components
     Components and Plugins: Filtering objects
     Components and Plugins: helpers for PCI discovery
     Components and Plugins: finding PCI objects during other discoveries
     Netloc API
    -
    -
    - - - - - - - -
    -
    -
    Related Pages
    -
    -
    -
    Here is a list of all related documentation pages:
    - - - - - - - - - - - - - - - - - - - - -
     Hardware Locality (hwloc) Introduction
     Terms and Definitions
     Command-Line Tools
     Environment Variables
     CPU and Memory Binding Overview
     I/O Devices
     Miscellaneous objects
     Object attributes
     Topology Attributes: Distances, Memory Attributes and CPU Kinds
     Importing and exporting topologies from/to XML files
     Synthetic topologies
     Interoperability With Other Software
     Thread Safety
     Components and plugins
     Embedding hwloc in Other Software
     Frequently Asked Questions (FAQ)
     Upgrading to the hwloc 2.0 API
     Network Locality (netloc)
     Netloc with Scotch
    -
    -
    -li>h1,.sm>li>h2,.sm>li>h3,.sm>li>h4,.sm>li>h5,.sm>li>h6{margin:0;padding:0}.sm ul{display:none}.sm li,.sm a{position:relative}.sm a{display:block}.sm a.disabled{cursor:not-allowed}.sm:after{content:"\00a0";display:block;height:0;font:0px/0 serif;clear:both;visibility:hidden;overflow:hidden}.sm,.sm *,.sm *:before,.sm *:after{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box}.sm-dox{background-image:url("tab_b.png")}.sm-dox a,.sm-dox a:focus,.sm-dox a:hover,.sm-dox a:active{padding:0px 12px;padding-right:43px;font-family:"Lucida Grande","Geneva","Helvetica",Arial,sans-serif;font-size:13px;font-weight:bold;line-height:36px;text-decoration:none;text-shadow:0px 1px 1px rgba(255,255,255,0.9);color:#283A5D;outline:none}.sm-dox a:hover{background-image:url("tab_a.png");background-repeat:repeat-x;color:#fff;text-shadow:0px 1px 1px #000}.sm-dox a.current{color:#D23600}.sm-dox a.disabled{color:#bbb}.sm-dox a span.sub-arrow{position:absolute;top:50%;margin-top:-14px;left:auto;right:3px;width:28px;height:28px;overflow:hidden;font:bold 12px/28px monospace !important;text-align:center;text-shadow:none;background:rgba(255,255,255,0.5);border-radius:5px}.sm-dox a.highlighted span.sub-arrow:before{display:block;content:'-'}.sm-dox>li:first-child>a,.sm-dox>li:first-child>:not(ul) a{border-radius:5px 5px 0 0}.sm-dox>li:last-child>a,.sm-dox>li:last-child>*:not(ul) a,.sm-dox>li:last-child>ul,.sm-dox>li:last-child>ul>li:last-child>a,.sm-dox>li:last-child>ul>li:last-child>*:not(ul) a,.sm-dox>li:last-child>ul>li:last-child>ul,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>a,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>*:not(ul) a,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>a,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>*:not(ul) a,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>ul,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>a,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>*:not(ul) a,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>ul{border-radius:0 0 5px 5px}.sm-dox>li:last-child>a.highlighted,.sm-dox>li:last-child>*:not(ul) a.highlighted,.sm-dox>li:last-child>ul>li:last-child>a.highlighted,.sm-dox>li:last-child>ul>li:last-child>*:not(ul) a.highlighted,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>a.highlighted,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>*:not(ul) a.highlighted,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>a.highlighted,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>*:not(ul) a.highlighted,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>a.highlighted,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>*:not(ul) a.highlighted{border-radius:0}.sm-dox ul{background:rgba(162,162,162,0.1)}.sm-dox ul a,.sm-dox ul a:focus,.sm-dox ul a:hover,.sm-dox ul a:active{font-size:12px;border-left:8px solid transparent;line-height:36px;text-shadow:none;background-color:white;background-image:none}.sm-dox ul a:hover{background-image:url("tab_a.png");background-repeat:repeat-x;color:#fff;text-shadow:0px 1px 1px #000}.sm-dox ul ul a,.sm-dox ul ul a:hover,.sm-dox ul ul a:focus,.sm-dox ul ul a:active{border-left:16px solid transparent}.sm-dox ul ul ul a,.sm-dox ul ul ul a:hover,.sm-dox ul ul ul a:focus,.sm-dox ul ul ul a:active{border-left:24px solid transparent}.sm-dox ul ul ul ul a,.sm-dox ul ul ul ul a:hover,.sm-dox ul ul ul ul a:focus,.sm-dox ul ul ul ul a:active{border-left:32px solid transparent}.sm-dox ul ul ul ul ul a,.sm-dox ul ul ul ul ul a:hover,.sm-dox ul ul ul ul ul a:focus,.sm-dox ul ul ul ul ul a:active{border-left:40px solid transparent}@media (min-width: 768px){.sm-dox ul{position:absolute;width:12em}.sm-dox li{float:left}.sm-dox.sm-rtl li{float:right}.sm-dox ul li,.sm-dox.sm-rtl ul li,.sm-dox.sm-vertical li{float:none}.sm-dox a{white-space:nowrap}.sm-dox ul a,.sm-dox.sm-vertical a{white-space:normal}.sm-dox .sm-nowrap>li>a,.sm-dox .sm-nowrap>li>:not(ul) a{white-space:nowrap}.sm-dox{padding:0 10px;background-image:url("tab_b.png");line-height:36px}.sm-dox a span.sub-arrow{top:50%;margin-top:-2px;right:12px;width:0;height:0;border-width:4px;border-style:solid dashed dashed dashed;border-color:#283A5D transparent transparent transparent;background:transparent;border-radius:0}.sm-dox a,.sm-dox a:focus,.sm-dox a:active,.sm-dox a:hover,.sm-dox a.highlighted{padding:0px 12px;background-image:url("tab_s.png");background-repeat:no-repeat;background-position:right;border-radius:0 !important}.sm-dox a:hover{background-image:url("tab_a.png");background-repeat:repeat-x;color:#fff;text-shadow:0px 1px 1px #000}.sm-dox a:hover span.sub-arrow{border-color:#fff transparent transparent transparent}.sm-dox a.has-submenu{padding-right:24px}.sm-dox li{border-top:0}.sm-dox>li>ul:before,.sm-dox>li>ul:after{content:'';position:absolute;top:-18px;left:30px;width:0;height:0;overflow:hidden;border-width:9px;border-style:dashed dashed solid dashed;border-color:transparent transparent #bbb transparent}.sm-dox>li>ul:after{top:-16px;left:31px;border-width:8px;border-color:transparent transparent #fff transparent}.sm-dox ul{border:1px solid #bbb;padding:5px 0;background:#fff;border-radius:5px !important;box-shadow:0 5px 9px rgba(0,0,0,0.2)}.sm-dox ul a span.sub-arrow{right:8px;top:50%;margin-top:-5px;border-width:5px;border-color:transparent transparent transparent #555;border-style:dashed dashed dashed solid}.sm-dox ul a,.sm-dox ul a:hover,.sm-dox ul a:focus,.sm-dox ul a:active,.sm-dox ul a.highlighted{color:#555;background-image:none;border:0 !important;color:#555;background-image:none}.sm-dox ul a:hover{background-image:url("tab_a.png");background-repeat:repeat-x;color:#fff;text-shadow:0px 1px 1px #000}.sm-dox ul a:hover span.sub-arrow{border-color:transparent transparent transparent #fff}.sm-dox span.scroll-up,.sm-dox span.scroll-down{position:absolute;display:none;visibility:hidden;overflow:hidden;background:#fff;height:36px}.sm-dox span.scroll-up:hover,.sm-dox span.scroll-down:hover{background:#eee}.sm-dox span.scroll-up:hover span.scroll-up-arrow,.sm-dox span.scroll-up:hover span.scroll-down-arrow{border-color:transparent transparent #D23600 transparent}.sm-dox span.scroll-down:hover span.scroll-down-arrow{border-color:#D23600 transparent transparent transparent}.sm-dox span.scroll-up-arrow,.sm-dox span.scroll-down-arrow{position:absolute;top:0;left:50%;margin-left:-6px;width:0;height:0;overflow:hidden;border-width:6px;border-style:dashed dashed solid dashed;border-color:transparent transparent #555 transparent}.sm-dox span.scroll-down-arrow{top:8px;border-style:solid dashed dashed dashed;border-color:#555 transparent transparent transparent}.sm-dox.sm-rtl a.has-submenu{padding-right:12px;padding-left:24px}.sm-dox.sm-rtl a span.sub-arrow{right:auto;left:12px}.sm-dox.sm-rtl.sm-vertical a.has-submenu{padding:10px 20px}.sm-dox.sm-rtl.sm-vertical a span.sub-arrow{right:auto;left:8px;border-style:dashed solid dashed dashed;border-color:transparent #555 transparent transparent}.sm-dox.sm-rtl>li>ul:before{left:auto;right:30px}.sm-dox.sm-rtl>li>ul:after{left:auto;right:31px}.sm-dox.sm-rtl ul a.has-submenu{padding:10px 20px !important}.sm-dox.sm-rtl ul a span.sub-arrow{right:auto;left:8px;border-style:dashed solid dashed dashed;border-color:transparent #555 transparent transparent}.sm-dox.sm-vertical{padding:10px 0;border-radius:5px}.sm-dox.sm-vertical a{padding:10px 20px}.sm-dox.sm-vertical a:hover,.sm-dox.sm-vertical a:focus,.sm-dox.sm-vertical a:active,.sm-dox.sm-vertical a.highlighted{background:#fff}.sm-dox.sm-vertical a.disabled{background-image:url("tab_b.png")}.sm-dox.sm-vertical a span.sub-arrow{right:8px;top:50%;margin-top:-5px;border-width:5px;border-style:dashed dashed dashed solid;border-color:transparent transparent transparent #555}.sm-dox.sm-vertical>li>ul:before,.sm-dox.sm-vertical>li>ul:after{display:none}.sm-dox.sm-vertical ul a{padding:10px 20px}.sm-dox.sm-vertical ul a:hover,.sm-dox.sm-vertical ul a:focus,.sm-dox.sm-vertical ul a:active,.sm-dox.sm-vertical ul a.highlighted{background:#eee}.sm-dox.sm-vertical ul a.disabled{background:#fff}} diff --git a/projects/hwloc/doc/v2.9.0/www.open-mpi.org-css.inc b/projects/hwloc/doc/v2.9.0/www.open-mpi.org-css.inc deleted file mode 100644 index 339ffeb0b..000000000 --- a/projects/hwloc/doc/v2.9.0/www.open-mpi.org-css.inc +++ /dev/null @@ -1,2 +0,0 @@ - - diff --git a/projects/hwloc/doc/v2.9.0/www.open-mpi.org-footer.inc b/projects/hwloc/doc/v2.9.0/www.open-mpi.org-footer.inc deleted file mode 100644 index 50e092203..000000000 --- a/projects/hwloc/doc/v2.9.0/www.open-mpi.org-footer.inc +++ /dev/null @@ -1,2 +0,0 @@ - diff --git a/projects/hwloc/doc/v2.9.1/a00089_source.php b/projects/hwloc/doc/v2.9.1/a00089_source.php deleted file mode 100644 index 1c556db5e..000000000 --- a/projects/hwloc/doc/v2.9.1/a00089_source.php +++ /dev/null @@ -1,927 +0,0 @@ - - - - - - - - -
    -
    -
    hwloc.h
    -
    -
    -
    1 /*
    -
    2  * Copyright © 2009 CNRS
    -
    3  * Copyright © 2009-2022 Inria. All rights reserved.
    -
    4  * Copyright © 2009-2012 Université Bordeaux
    -
    5  * Copyright © 2009-2020 Cisco Systems, Inc. All rights reserved.
    -
    6  * See COPYING in top-level directory.
    -
    7  */
    -
    8 
    -
    9 /*=====================================================================
    -
    10  * PLEASE GO READ THE DOCUMENTATION!
    -
    11  * ------------------------------------------------
    -
    12  * $tarball_directory/doc/doxygen-doc/
    -
    13  * or
    -
    14  * https://www.open-mpi.org/projects/hwloc/doc/
    -
    15  *=====================================================================
    -
    16  *
    -
    17  * FAIR WARNING: Do NOT expect to be able to figure out all the
    -
    18  * subtleties of hwloc by simply reading function prototypes and
    -
    19  * constant descrptions here in this file.
    -
    20  *
    -
    21  * Hwloc has wonderful documentation in both PDF and HTML formats for
    -
    22  * your reading pleasure. The formal documentation explains a LOT of
    -
    23  * hwloc-specific concepts, provides definitions, and discusses the
    -
    24  * "big picture" for many of the things that you'll find here in this
    -
    25  * header file.
    -
    26  *
    -
    27  * The PDF/HTML documentation was generated via Doxygen; much of what
    -
    28  * you'll see in there is also here in this file. BUT THERE IS A LOT
    -
    29  * THAT IS IN THE PDF/HTML THAT IS ***NOT*** IN hwloc.h!
    -
    30  *
    -
    31  * There are entire paragraph-length descriptions, discussions, and
    -
    32  * pretty pictures to explain subtle corner cases, provide concrete
    -
    33  * examples, etc.
    -
    34  *
    -
    35  * Please, go read the documentation. :-)
    -
    36  *
    -
    37  * Moreover there are several examples of hwloc use under doc/examples
    -
    38  * in the source tree.
    -
    39  *
    -
    40  *=====================================================================*/
    -
    41 
    -
    53 #ifndef HWLOC_H
    -
    54 #define HWLOC_H
    -
    55 
    -
    56 #include "hwloc/autogen/config.h"
    -
    57 
    -
    58 #include <sys/types.h>
    -
    59 #include <stdio.h>
    -
    60 #include <string.h>
    -
    61 #include <limits.h>
    -
    62 
    -
    63 /*
    -
    64  * Symbol transforms
    -
    65  */
    -
    66 #include "hwloc/rename.h"
    -
    67 
    -
    68 /*
    -
    69  * Bitmap definitions
    -
    70  */
    -
    71 
    -
    72 #include "hwloc/bitmap.h"
    -
    73 
    -
    74 
    -
    75 #ifdef __cplusplus
    -
    76 extern "C" {
    -
    77 #endif
    -
    78 
    -
    79 
    -
    96 #define HWLOC_API_VERSION 0x00020800
    -
    97 
    -
    102 HWLOC_DECLSPEC unsigned hwloc_get_api_version(void);
    -
    103 
    -
    105 #define HWLOC_COMPONENT_ABI 7
    -
    106 
    -
    140 typedef hwloc_bitmap_t hwloc_cpuset_t;
    -
    142 typedef hwloc_const_bitmap_t hwloc_const_cpuset_t;
    -
    143 
    -
    157 typedef hwloc_bitmap_t hwloc_nodeset_t;
    -
    160 typedef hwloc_const_bitmap_t hwloc_const_nodeset_t;
    -
    161 
    -
    176 typedef enum {
    -
    177 
    -
    179 #define HWLOC_OBJ_TYPE_MIN HWLOC_OBJ_MACHINE /* Sentinel value */
    -
    182  HWLOC_OBJ_MACHINE,
    -
    191  HWLOC_OBJ_PACKAGE,
    -
    197  HWLOC_OBJ_CORE,
    -
    201  HWLOC_OBJ_PU,
    -
    213  HWLOC_OBJ_L1CACHE,
    -
    214  HWLOC_OBJ_L2CACHE,
    -
    215  HWLOC_OBJ_L3CACHE,
    -
    216  HWLOC_OBJ_L4CACHE,
    -
    217  HWLOC_OBJ_L5CACHE,
    -
    219  HWLOC_OBJ_L1ICACHE,
    -
    220  HWLOC_OBJ_L2ICACHE,
    -
    221  HWLOC_OBJ_L3ICACHE,
    -
    223  HWLOC_OBJ_GROUP,
    -
    236  HWLOC_OBJ_NUMANODE,
    -
    257  HWLOC_OBJ_BRIDGE,
    -
    269  HWLOC_OBJ_PCI_DEVICE,
    -
    279  HWLOC_OBJ_OS_DEVICE,
    -
    290  HWLOC_OBJ_MISC,
    -
    305  HWLOC_OBJ_MEMCACHE,
    -
    318  HWLOC_OBJ_DIE,
    -
    322  HWLOC_OBJ_TYPE_MAX
    -
    323 } hwloc_obj_type_t;
    -
    324 
    -
    326 typedef enum hwloc_obj_cache_type_e {
    -
    327  HWLOC_OBJ_CACHE_UNIFIED,
    -
    328  HWLOC_OBJ_CACHE_DATA,
    -
    329  HWLOC_OBJ_CACHE_INSTRUCTION
    -
    330 } hwloc_obj_cache_type_t;
    -
    331 
    -
    333 typedef enum hwloc_obj_bridge_type_e {
    -
    334  HWLOC_OBJ_BRIDGE_HOST,
    -
    335  HWLOC_OBJ_BRIDGE_PCI
    -
    336 } hwloc_obj_bridge_type_t;
    -
    337 
    -
    339 typedef enum hwloc_obj_osdev_type_e {
    -
    340  HWLOC_OBJ_OSDEV_BLOCK,
    -
    342  HWLOC_OBJ_OSDEV_GPU,
    -
    345  HWLOC_OBJ_OSDEV_NETWORK,
    -
    347  HWLOC_OBJ_OSDEV_OPENFABRICS,
    -
    351  HWLOC_OBJ_OSDEV_DMA,
    -
    353  HWLOC_OBJ_OSDEV_COPROC
    -
    356 } hwloc_obj_osdev_type_t;
    -
    357 
    -
    377 HWLOC_DECLSPEC int hwloc_compare_types (hwloc_obj_type_t type1, hwloc_obj_type_t type2) __hwloc_attribute_const;
    -
    378 
    -
    380 #define HWLOC_TYPE_UNORDERED INT_MAX
    -
    381 
    -
    390 union hwloc_obj_attr_u;
    -
    391 
    -
    396 struct hwloc_obj {
    -
    397  /* physical information */
    -
    398  hwloc_obj_type_t type;
    -
    399  char *subtype;
    -
    401  unsigned os_index;
    -
    406 #define HWLOC_UNKNOWN_INDEX (unsigned)-1
    -
    407 
    -
    408  char *name;
    -
    413  hwloc_uint64_t total_memory;
    -
    415  union hwloc_obj_attr_u *attr;
    -
    418  /* global position */
    -
    419  int depth;
    -
    434  unsigned logical_index;
    -
    441  /* cousins are all objects of the same type (and depth) across the entire topology */
    -
    442  struct hwloc_obj *next_cousin;
    -
    443  struct hwloc_obj *prev_cousin;
    -
    445  /* children of the same parent are siblings, even if they may have different type and depth */
    -
    446  struct hwloc_obj *parent;
    -
    447  unsigned sibling_rank;
    -
    448  struct hwloc_obj *next_sibling;
    -
    449  struct hwloc_obj *prev_sibling;
    -
    452  unsigned arity;
    -
    456  struct hwloc_obj **children;
    -
    457  struct hwloc_obj *first_child;
    -
    458  struct hwloc_obj *last_child;
    -
    461  int symmetric_subtree;
    -
    472  unsigned memory_arity;
    -
    475  struct hwloc_obj *memory_first_child;
    -
    490  unsigned io_arity;
    -
    493  struct hwloc_obj *io_first_child;
    -
    502  unsigned misc_arity;
    -
    505  struct hwloc_obj *misc_first_child;
    -
    511  /* cpusets and nodesets */
    -
    512  hwloc_cpuset_t cpuset;
    -
    527  hwloc_cpuset_t complete_cpuset;
    -
    540  hwloc_nodeset_t nodeset;
    -
    562  hwloc_nodeset_t complete_nodeset;
    -
    578  struct hwloc_info_s *infos;
    -
    579  unsigned infos_count;
    -
    581  /* misc */
    -
    582  void *userdata;
    -
    587  hwloc_uint64_t gp_index;
    -
    592 };
    -
    596 typedef struct hwloc_obj * hwloc_obj_t;
    -
    597 
    -
    599 union hwloc_obj_attr_u {
    -
    601  struct hwloc_numanode_attr_s {
    -
    602  hwloc_uint64_t local_memory;
    -
    603  unsigned page_types_len;
    -
    609  struct hwloc_memory_page_type_s {
    -
    610  hwloc_uint64_t size;
    -
    611  hwloc_uint64_t count;
    -
    612  } * page_types;
    -
    613  } numanode;
    -
    614 
    -
    616  struct hwloc_cache_attr_s {
    -
    617  hwloc_uint64_t size;
    -
    618  unsigned depth;
    -
    619  unsigned linesize;
    -
    620  int associativity;
    -
    622  hwloc_obj_cache_type_t type;
    -
    623  } cache;
    -
    625  struct hwloc_group_attr_s {
    -
    626  unsigned depth;
    -
    628  unsigned kind;
    -
    629  unsigned subkind;
    -
    630  unsigned char dont_merge;
    -
    631  } group;
    -
    633  struct hwloc_pcidev_attr_s {
    -
    634 #ifndef HWLOC_HAVE_32BITS_PCI_DOMAIN
    -
    635  unsigned short domain; /* Only 16bits PCI domains are supported by default */
    -
    636 #else
    -
    637  unsigned int domain; /* 32bits PCI domain support break the library ABI, hence it's disabled by default */
    -
    638 #endif
    -
    639  unsigned char bus, dev, func;
    -
    640  unsigned short class_id;
    -
    641  unsigned short vendor_id, device_id, subvendor_id, subdevice_id;
    -
    642  unsigned char revision;
    -
    643  float linkspeed; /* in GB/s */
    -
    644  } pcidev;
    -
    646  struct hwloc_bridge_attr_s {
    -
    647  union {
    -
    648  struct hwloc_pcidev_attr_s pci;
    -
    649  } upstream;
    -
    650  hwloc_obj_bridge_type_t upstream_type;
    -
    651  union {
    -
    652  struct {
    -
    653 #ifndef HWLOC_HAVE_32BITS_PCI_DOMAIN
    -
    654  unsigned short domain; /* Only 16bits PCI domains are supported by default */
    -
    655 #else
    -
    656  unsigned int domain; /* 32bits PCI domain support break the library ABI, hence it's disabled by default */
    -
    657 #endif
    -
    658  unsigned char secondary_bus, subordinate_bus;
    -
    659  } pci;
    -
    660  } downstream;
    -
    661  hwloc_obj_bridge_type_t downstream_type;
    -
    662  unsigned depth;
    -
    663  } bridge;
    -
    665  struct hwloc_osdev_attr_s {
    -
    666  hwloc_obj_osdev_type_t type;
    -
    667  } osdev;
    -
    668 };
    -
    669 
    -
    674 struct hwloc_info_s {
    -
    675  char *name;
    -
    676  char *value;
    -
    677 };
    -
    678 
    -
    687 struct hwloc_topology;
    -
    692 typedef struct hwloc_topology * hwloc_topology_t;
    -
    693 
    -
    700 HWLOC_DECLSPEC int hwloc_topology_init (hwloc_topology_t *topologyp);
    -
    701 
    -
    722 HWLOC_DECLSPEC int hwloc_topology_load(hwloc_topology_t topology);
    -
    723 
    -
    728 HWLOC_DECLSPEC void hwloc_topology_destroy (hwloc_topology_t topology);
    -
    729 
    -
    740 HWLOC_DECLSPEC int hwloc_topology_dup(hwloc_topology_t *newtopology, hwloc_topology_t oldtopology);
    -
    741 
    -
    759 HWLOC_DECLSPEC int hwloc_topology_abi_check(hwloc_topology_t topology);
    -
    760 
    -
    772 HWLOC_DECLSPEC void hwloc_topology_check(hwloc_topology_t topology);
    -
    773 
    -
    794 HWLOC_DECLSPEC int hwloc_topology_get_depth(hwloc_topology_t __hwloc_restrict topology) __hwloc_attribute_pure;
    -
    795 
    -
    819 HWLOC_DECLSPEC int hwloc_get_type_depth (hwloc_topology_t topology, hwloc_obj_type_t type);
    -
    820 
    -
    821 enum hwloc_get_type_depth_e {
    -
    822  HWLOC_TYPE_DEPTH_UNKNOWN = -1,
    -
    823  HWLOC_TYPE_DEPTH_MULTIPLE = -2,
    -
    824  HWLOC_TYPE_DEPTH_NUMANODE = -3,
    -
    825  HWLOC_TYPE_DEPTH_BRIDGE = -4,
    -
    826  HWLOC_TYPE_DEPTH_PCI_DEVICE = -5,
    -
    827  HWLOC_TYPE_DEPTH_OS_DEVICE = -6,
    -
    828  HWLOC_TYPE_DEPTH_MISC = -7,
    -
    829  HWLOC_TYPE_DEPTH_MEMCACHE = -8
    -
    830 };
    -
    831 
    -
    851 HWLOC_DECLSPEC int hwloc_get_memory_parents_depth (hwloc_topology_t topology);
    -
    852 
    -
    866 static __hwloc_inline int
    -
    867 hwloc_get_type_or_below_depth (hwloc_topology_t topology, hwloc_obj_type_t type) __hwloc_attribute_pure;
    -
    868 
    -
    882 static __hwloc_inline int
    -
    883 hwloc_get_type_or_above_depth (hwloc_topology_t topology, hwloc_obj_type_t type) __hwloc_attribute_pure;
    -
    884 
    -
    892 HWLOC_DECLSPEC hwloc_obj_type_t hwloc_get_depth_type (hwloc_topology_t topology, int depth) __hwloc_attribute_pure;
    -
    893 
    -
    896 HWLOC_DECLSPEC unsigned hwloc_get_nbobjs_by_depth (hwloc_topology_t topology, int depth) __hwloc_attribute_pure;
    -
    897 
    -
    903 static __hwloc_inline int
    -
    904 hwloc_get_nbobjs_by_type (hwloc_topology_t topology, hwloc_obj_type_t type) __hwloc_attribute_pure;
    -
    905 
    -
    910 static __hwloc_inline hwloc_obj_t
    -
    911 hwloc_get_root_obj (hwloc_topology_t topology) __hwloc_attribute_pure;
    -
    912 
    -
    914 HWLOC_DECLSPEC hwloc_obj_t hwloc_get_obj_by_depth (hwloc_topology_t topology, int depth, unsigned idx) __hwloc_attribute_pure;
    -
    915 
    -
    922 static __hwloc_inline hwloc_obj_t
    -
    923 hwloc_get_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx) __hwloc_attribute_pure;
    -
    924 
    -
    929 static __hwloc_inline hwloc_obj_t
    -
    930 hwloc_get_next_obj_by_depth (hwloc_topology_t topology, int depth, hwloc_obj_t prev);
    -
    931 
    -
    938 static __hwloc_inline hwloc_obj_t
    -
    939 hwloc_get_next_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type,
    -
    940  hwloc_obj_t prev);
    -
    941 
    -
    958 HWLOC_DECLSPEC const char * hwloc_obj_type_string (hwloc_obj_type_t type) __hwloc_attribute_const;
    -
    959 
    -
    977 HWLOC_DECLSPEC int hwloc_obj_type_snprintf(char * __hwloc_restrict string, size_t size,
    -
    978  hwloc_obj_t obj,
    -
    979  int verbose);
    -
    980 
    -
    992 HWLOC_DECLSPEC int hwloc_obj_attr_snprintf(char * __hwloc_restrict string, size_t size,
    -
    993  hwloc_obj_t obj, const char * __hwloc_restrict separator,
    -
    994  int verbose);
    -
    995 
    -
    1019 HWLOC_DECLSPEC int hwloc_type_sscanf(const char *string,
    -
    1020  hwloc_obj_type_t *typep,
    -
    1021  union hwloc_obj_attr_u *attrp, size_t attrsize);
    -
    1022 
    -
    1044 HWLOC_DECLSPEC int hwloc_type_sscanf_as_depth(const char *string,
    -
    1045  hwloc_obj_type_t *typep,
    -
    1046  hwloc_topology_t topology, int *depthp);
    -
    1047 
    -
    1063 static __hwloc_inline const char *
    -
    1064 hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name) __hwloc_attribute_pure;
    -
    1065 
    -
    1082 HWLOC_DECLSPEC int hwloc_obj_add_info(hwloc_obj_t obj, const char *name, const char *value);
    -
    1083 
    -
    1155 typedef enum {
    -
    1158  HWLOC_CPUBIND_PROCESS = (1<<0),
    -
    1159 
    -
    1162  HWLOC_CPUBIND_THREAD = (1<<1),
    -
    1163 
    -
    1187  HWLOC_CPUBIND_STRICT = (1<<2),
    -
    1188 
    -
    1204  HWLOC_CPUBIND_NOMEMBIND = (1<<3)
    -
    1205 } hwloc_cpubind_flags_t;
    -
    1206 
    -
    1212 HWLOC_DECLSPEC int hwloc_set_cpubind(hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags);
    -
    1213 
    -
    1220 HWLOC_DECLSPEC int hwloc_get_cpubind(hwloc_topology_t topology, hwloc_cpuset_t set, int flags);
    -
    1221 
    -
    1233 HWLOC_DECLSPEC int hwloc_set_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_cpuset_t set, int flags);
    -
    1234 
    -
    1250 HWLOC_DECLSPEC int hwloc_get_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags);
    -
    1251 
    -
    1252 #ifdef hwloc_thread_t
    -
    1260 HWLOC_DECLSPEC int hwloc_set_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_const_cpuset_t set, int flags);
    -
    1261 #endif
    -
    1262 
    -
    1263 #ifdef hwloc_thread_t
    -
    1275 HWLOC_DECLSPEC int hwloc_get_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_cpuset_t set, int flags);
    -
    1276 #endif
    -
    1277 
    -
    1295 HWLOC_DECLSPEC int hwloc_get_last_cpu_location(hwloc_topology_t topology, hwloc_cpuset_t set, int flags);
    -
    1296 
    -
    1317 HWLOC_DECLSPEC int hwloc_get_proc_last_cpu_location(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags);
    -
    1318 
    -
    1398 typedef enum {
    -
    1406  HWLOC_MEMBIND_DEFAULT = 0,
    -
    1407 
    -
    1417  HWLOC_MEMBIND_FIRSTTOUCH = 1,
    -
    1418 
    -
    1421  HWLOC_MEMBIND_BIND = 2,
    -
    1422 
    -
    1430  HWLOC_MEMBIND_INTERLEAVE = 3,
    -
    1431 
    -
    1437  HWLOC_MEMBIND_NEXTTOUCH = 4,
    -
    1438 
    -
    1445  HWLOC_MEMBIND_MIXED = -1
    -
    1446 } hwloc_membind_policy_t;
    -
    1447 
    -
    1461 typedef enum {
    -
    1466  HWLOC_MEMBIND_PROCESS = (1<<0),
    -
    1467 
    -
    1471  HWLOC_MEMBIND_THREAD = (1<<1),
    -
    1472 
    -
    1479  HWLOC_MEMBIND_STRICT = (1<<2),
    -
    1480 
    -
    1485  HWLOC_MEMBIND_MIGRATE = (1<<3),
    -
    1486 
    -
    1498  HWLOC_MEMBIND_NOCPUBIND = (1<<4),
    -
    1499 
    -
    1509  HWLOC_MEMBIND_BYNODESET = (1<<5)
    -
    1510 } hwloc_membind_flags_t;
    -
    1511 
    -
    1527 HWLOC_DECLSPEC int hwloc_set_membind(hwloc_topology_t topology, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags);
    -
    1528 
    -
    1576 HWLOC_DECLSPEC int hwloc_get_membind(hwloc_topology_t topology, hwloc_bitmap_t set, hwloc_membind_policy_t * policy, int flags);
    -
    1577 
    -
    1590 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);
    -
    1591 
    -
    1634 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);
    -
    1635 
    -
    1646 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);
    -
    1647 
    -
    1678 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);
    -
    1679 
    -
    1700 HWLOC_DECLSPEC int hwloc_get_area_memlocation(hwloc_topology_t topology, const void *addr, size_t len, hwloc_bitmap_t set, int flags);
    -
    1701 
    -
    1709 HWLOC_DECLSPEC void *hwloc_alloc(hwloc_topology_t topology, size_t len);
    -
    1710 
    -
    1725 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;
    -
    1726 
    -
    1739 static __hwloc_inline void *
    -
    1740 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;
    -
    1741 
    -
    1745 HWLOC_DECLSPEC int hwloc_free(hwloc_topology_t topology, void *addr, size_t len);
    -
    1746 
    -
    1783 HWLOC_DECLSPEC int hwloc_topology_set_pid(hwloc_topology_t __hwloc_restrict topology, hwloc_pid_t pid);
    -
    1784 
    -
    1813 HWLOC_DECLSPEC int hwloc_topology_set_synthetic(hwloc_topology_t __hwloc_restrict topology, const char * __hwloc_restrict description);
    -
    1814 
    -
    1841 HWLOC_DECLSPEC int hwloc_topology_set_xml(hwloc_topology_t __hwloc_restrict topology, const char * __hwloc_restrict xmlpath);
    -
    1842 
    -
    1869 HWLOC_DECLSPEC int hwloc_topology_set_xmlbuffer(hwloc_topology_t __hwloc_restrict topology, const char * __hwloc_restrict buffer, int size);
    -
    1870 
    -
    1873 enum hwloc_topology_components_flag_e {
    -
    1877  HWLOC_TOPOLOGY_COMPONENTS_FLAG_BLACKLIST = (1UL<<0)
    -
    1878 };
    -
    1879 
    -
    1894 HWLOC_DECLSPEC int hwloc_topology_set_components(hwloc_topology_t __hwloc_restrict topology, unsigned long flags, const char * __hwloc_restrict name);
    -
    1895 
    -
    1914 enum hwloc_topology_flags_e {
    -
    1936  HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED = (1UL<<0),
    -
    1937 
    -
    1956  HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM = (1UL<<1),
    -
    1957 
    -
    1977  HWLOC_TOPOLOGY_FLAG_THISSYSTEM_ALLOWED_RESOURCES = (1UL<<2),
    -
    1978 
    -
    2001  HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT = (1UL<<3),
    -
    2002 
    -
    2026  HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_CPUBINDING = (1UL<<4),
    -
    2027 
    -
    2048  HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_MEMBINDING = (1UL<<5),
    -
    2049 
    -
    2063  HWLOC_TOPOLOGY_FLAG_DONT_CHANGE_BINDING = (1UL<<6),
    -
    2064 
    -
    2070  HWLOC_TOPOLOGY_FLAG_NO_DISTANCES = (1UL<<7),
    -
    2071 
    -
    2076  HWLOC_TOPOLOGY_FLAG_NO_MEMATTRS = (1UL<<8),
    -
    2077 
    -
    2082  HWLOC_TOPOLOGY_FLAG_NO_CPUKINDS = (1UL<<9)
    -
    2083 };
    -
    2084 
    -
    2096 HWLOC_DECLSPEC int hwloc_topology_set_flags (hwloc_topology_t topology, unsigned long flags);
    -
    2097 
    -
    2107 HWLOC_DECLSPEC unsigned long hwloc_topology_get_flags (hwloc_topology_t topology);
    -
    2108 
    -
    2116 HWLOC_DECLSPEC int hwloc_topology_is_thissystem(hwloc_topology_t __hwloc_restrict topology) __hwloc_attribute_pure;
    -
    2117 
    -
    2119 struct hwloc_topology_discovery_support {
    -
    2121  unsigned char pu;
    -
    2123  unsigned char numa;
    -
    2125  unsigned char numa_memory;
    -
    2127  unsigned char disallowed_pu;
    -
    2129  unsigned char disallowed_numa;
    -
    2131  unsigned char cpukind_efficiency;
    -
    2132 };
    -
    2133 
    -
    2139 struct hwloc_topology_cpubind_support {
    -
    2141  unsigned char set_thisproc_cpubind;
    -
    2143  unsigned char get_thisproc_cpubind;
    -
    2145  unsigned char set_proc_cpubind;
    -
    2147  unsigned char get_proc_cpubind;
    -
    2149  unsigned char set_thisthread_cpubind;
    -
    2151  unsigned char get_thisthread_cpubind;
    -
    2153  unsigned char set_thread_cpubind;
    -
    2155  unsigned char get_thread_cpubind;
    -
    2157  unsigned char get_thisproc_last_cpu_location;
    -
    2159  unsigned char get_proc_last_cpu_location;
    -
    2161  unsigned char get_thisthread_last_cpu_location;
    -
    2162 };
    -
    2163 
    -
    2169 struct hwloc_topology_membind_support {
    -
    2171  unsigned char set_thisproc_membind;
    -
    2173  unsigned char get_thisproc_membind;
    -
    2175  unsigned char set_proc_membind;
    -
    2177  unsigned char get_proc_membind;
    -
    2179  unsigned char set_thisthread_membind;
    -
    2181  unsigned char get_thisthread_membind;
    -
    2183  unsigned char set_area_membind;
    -
    2185  unsigned char get_area_membind;
    -
    2187  unsigned char alloc_membind;
    -
    2189  unsigned char firsttouch_membind;
    -
    2191  unsigned char bind_membind;
    -
    2193  unsigned char interleave_membind;
    -
    2195  unsigned char nexttouch_membind;
    -
    2197  unsigned char migrate_membind;
    -
    2199  unsigned char get_area_memlocation;
    -
    2200 };
    -
    2201 
    -
    2204 struct hwloc_topology_misc_support {
    -
    2206  unsigned char imported_support;
    -
    2207 };
    -
    2208 
    -
    2215 struct hwloc_topology_support {
    -
    2216  struct hwloc_topology_discovery_support *discovery;
    -
    2217  struct hwloc_topology_cpubind_support *cpubind;
    -
    2218  struct hwloc_topology_membind_support *membind;
    -
    2219  struct hwloc_topology_misc_support *misc;
    -
    2220 };
    -
    2221 
    -
    2243 HWLOC_DECLSPEC const struct hwloc_topology_support *hwloc_topology_get_support(hwloc_topology_t __hwloc_restrict topology);
    -
    2244 
    -
    2254 enum hwloc_type_filter_e {
    -
    2260  HWLOC_TYPE_FILTER_KEEP_ALL = 0,
    -
    2261 
    -
    2268  HWLOC_TYPE_FILTER_KEEP_NONE = 1,
    -
    2269 
    -
    2282  HWLOC_TYPE_FILTER_KEEP_STRUCTURE = 2,
    -
    2283 
    -
    2297  HWLOC_TYPE_FILTER_KEEP_IMPORTANT = 3
    -
    2298 };
    -
    2299 
    -
    2302 HWLOC_DECLSPEC int hwloc_topology_set_type_filter(hwloc_topology_t topology, hwloc_obj_type_t type, enum hwloc_type_filter_e filter);
    -
    2303 
    -
    2306 HWLOC_DECLSPEC int hwloc_topology_get_type_filter(hwloc_topology_t topology, hwloc_obj_type_t type, enum hwloc_type_filter_e *filter);
    -
    2307 
    -
    2312 HWLOC_DECLSPEC int hwloc_topology_set_all_types_filter(hwloc_topology_t topology, enum hwloc_type_filter_e filter);
    -
    2313 
    -
    2318 HWLOC_DECLSPEC int hwloc_topology_set_cache_types_filter(hwloc_topology_t topology, enum hwloc_type_filter_e filter);
    -
    2319 
    -
    2324 HWLOC_DECLSPEC int hwloc_topology_set_icache_types_filter(hwloc_topology_t topology, enum hwloc_type_filter_e filter);
    -
    2325 
    -
    2328 HWLOC_DECLSPEC int hwloc_topology_set_io_types_filter(hwloc_topology_t topology, enum hwloc_type_filter_e filter);
    -
    2329 
    -
    2340 HWLOC_DECLSPEC void hwloc_topology_set_userdata(hwloc_topology_t topology, const void *userdata);
    -
    2341 
    -
    2347 HWLOC_DECLSPEC void * hwloc_topology_get_userdata(hwloc_topology_t topology);
    -
    2348 
    -
    2358 enum hwloc_restrict_flags_e {
    -
    2364  HWLOC_RESTRICT_FLAG_REMOVE_CPULESS = (1UL<<0),
    -
    2365 
    -
    2370  HWLOC_RESTRICT_FLAG_BYNODESET = (1UL<<3),
    -
    2371 
    -
    2377  HWLOC_RESTRICT_FLAG_REMOVE_MEMLESS = (1UL<<4),
    -
    2378 
    -
    2383  HWLOC_RESTRICT_FLAG_ADAPT_MISC = (1UL<<1),
    -
    2384 
    -
    2389  HWLOC_RESTRICT_FLAG_ADAPT_IO = (1UL<<2)
    -
    2390 };
    -
    2391 
    -
    2416 HWLOC_DECLSPEC int hwloc_topology_restrict(hwloc_topology_t __hwloc_restrict topology, hwloc_const_bitmap_t set, unsigned long flags);
    -
    2417 
    -
    2419 enum hwloc_allow_flags_e {
    -
    2424  HWLOC_ALLOW_FLAG_ALL = (1UL<<0),
    -
    2425 
    -
    2433  HWLOC_ALLOW_FLAG_LOCAL_RESTRICTIONS = (1UL<<1),
    -
    2434 
    -
    2437  HWLOC_ALLOW_FLAG_CUSTOM = (1UL<<2)
    -
    2438 };
    -
    2439 
    -
    2455 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);
    -
    2456 
    -
    2478 HWLOC_DECLSPEC hwloc_obj_t hwloc_topology_insert_misc_object(hwloc_topology_t topology, hwloc_obj_t parent, const char *name);
    -
    2479 
    -
    2487 HWLOC_DECLSPEC hwloc_obj_t hwloc_topology_alloc_group_object(hwloc_topology_t topology);
    -
    2488 
    -
    2535 HWLOC_DECLSPEC hwloc_obj_t hwloc_topology_insert_group_object(hwloc_topology_t topology, hwloc_obj_t group);
    -
    2536 
    -
    2546 HWLOC_DECLSPEC int hwloc_obj_add_other_obj_sets(hwloc_obj_t dst, hwloc_obj_t src);
    -
    2547 
    -
    2562 HWLOC_DECLSPEC int hwloc_topology_refresh(hwloc_topology_t topology);
    -
    2563 
    -
    2568 #ifdef __cplusplus
    -
    2569 } /* extern "C" */
    -
    2570 #endif
    -
    2571 
    -
    2572 
    -
    2573 /* high-level helpers */
    -
    2574 #include "hwloc/helper.h"
    -
    2575 
    -
    2576 /* inline code of some functions above */
    -
    2577 #include "hwloc/inlines.h"
    -
    2578 
    -
    2579 /* memory attributes */
    -
    2580 #include "hwloc/memattrs.h"
    -
    2581 
    -
    2582 /* kinds of CPU cores */
    -
    2583 #include "hwloc/cpukinds.h"
    -
    2584 
    -
    2585 /* exporting to XML or synthetic */
    -
    2586 #include "hwloc/export.h"
    -
    2587 
    -
    2588 /* distances */
    -
    2589 #include "hwloc/distances.h"
    -
    2590 
    -
    2591 /* topology diffs */
    -
    2592 #include "hwloc/diff.h"
    -
    2593 
    -
    2594 /* deprecated headers */
    -
    2595 #include "hwloc/deprecated.h"
    -
    2596 
    -
    2597 #endif /* HWLOC_H */
    -
    hwloc_get_api_version
    unsigned hwloc_get_api_version(void)
    Indicate at runtime which hwloc API version was used at build time.
    -
    hwloc_const_cpuset_t
    hwloc_const_bitmap_t hwloc_const_cpuset_t
    A non-modifiable hwloc_cpuset_t.
    Definition: hwloc.h:142
    -
    hwloc_const_nodeset_t
    hwloc_const_bitmap_t hwloc_const_nodeset_t
    A non-modifiable hwloc_nodeset_t.
    Definition: hwloc.h:160
    -
    hwloc_nodeset_t
    hwloc_bitmap_t hwloc_nodeset_t
    A node set is a bitmap whose bits are set according to NUMA memory node physical OS indexes.
    Definition: hwloc.h:157
    -
    hwloc_cpuset_t
    hwloc_bitmap_t hwloc_cpuset_t
    A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
    Definition: hwloc.h:140
    -
    hwloc_compare_types
    int hwloc_compare_types(hwloc_obj_type_t type1, hwloc_obj_type_t type2)
    Compare the depth of two object types.
    -
    hwloc_obj_bridge_type_e
    hwloc_obj_bridge_type_e
    Type of one side (upstream or downstream) of an I/O bridge.
    Definition: hwloc.h:333
    -
    hwloc_obj_cache_type_t
    enum hwloc_obj_cache_type_e hwloc_obj_cache_type_t
    Cache type.
    -
    hwloc_obj_osdev_type_e
    hwloc_obj_osdev_type_e
    Type of a OS device.
    Definition: hwloc.h:339
    -
    hwloc_obj_cache_type_e
    hwloc_obj_cache_type_e
    Cache type.
    Definition: hwloc.h:326
    -
    hwloc_obj_osdev_type_t
    enum hwloc_obj_osdev_type_e hwloc_obj_osdev_type_t
    Type of a OS device.
    -
    hwloc_obj_bridge_type_t
    enum hwloc_obj_bridge_type_e hwloc_obj_bridge_type_t
    Type of one side (upstream or downstream) of an I/O bridge.
    -
    hwloc_obj_type_t
    hwloc_obj_type_t
    Type of topology object.
    Definition: hwloc.h:176
    -
    HWLOC_OBJ_BRIDGE_HOST
    @ HWLOC_OBJ_BRIDGE_HOST
    Host-side of a bridge, only possible upstream.
    Definition: hwloc.h:334
    -
    HWLOC_OBJ_BRIDGE_PCI
    @ HWLOC_OBJ_BRIDGE_PCI
    PCI-side of a bridge.
    Definition: hwloc.h:335
    -
    HWLOC_OBJ_OSDEV_COPROC
    @ HWLOC_OBJ_OSDEV_COPROC
    Operating system co-processor device. For instance "opencl0d0" for a OpenCL device,...
    Definition: hwloc.h:353
    -
    HWLOC_OBJ_OSDEV_OPENFABRICS
    @ HWLOC_OBJ_OSDEV_OPENFABRICS
    Operating system openfabrics device. For instance the "mlx4_0" InfiniBand HCA, "hfi1_0" Omni-Path int...
    Definition: hwloc.h:347
    -
    HWLOC_OBJ_OSDEV_BLOCK
    @ HWLOC_OBJ_OSDEV_BLOCK
    Operating system block device, or non-volatile memory device. For instance "sda" or "dax2....
    Definition: hwloc.h:340
    -
    HWLOC_OBJ_OSDEV_DMA
    @ HWLOC_OBJ_OSDEV_DMA
    Operating system dma engine device. For instance the "dma0chan0" DMA channel on Linux.
    Definition: hwloc.h:351
    -
    HWLOC_OBJ_OSDEV_GPU
    @ HWLOC_OBJ_OSDEV_GPU
    Operating system GPU device. For instance ":0.0" for a GL display, "card0" for a Linux DRM device.
    Definition: hwloc.h:342
    -
    HWLOC_OBJ_OSDEV_NETWORK
    @ HWLOC_OBJ_OSDEV_NETWORK
    Operating system network device. For instance the "eth0" interface on Linux.
    Definition: hwloc.h:345
    -
    HWLOC_OBJ_CACHE_UNIFIED
    @ HWLOC_OBJ_CACHE_UNIFIED
    Unified cache.
    Definition: hwloc.h:327
    -
    HWLOC_OBJ_CACHE_INSTRUCTION
    @ HWLOC_OBJ_CACHE_INSTRUCTION
    Instruction cache (filtered out by default).
    Definition: hwloc.h:329
    -
    HWLOC_OBJ_CACHE_DATA
    @ HWLOC_OBJ_CACHE_DATA
    Data cache.
    Definition: hwloc.h:328
    -
    HWLOC_OBJ_MEMCACHE
    @ HWLOC_OBJ_MEMCACHE
    Memory-side cache (filtered out by default). A cache in front of a specific NUMA node.
    Definition: hwloc.h:305
    -
    HWLOC_OBJ_L2ICACHE
    @ HWLOC_OBJ_L2ICACHE
    Level 2 instruction Cache (filtered out by default).
    Definition: hwloc.h:220
    -
    HWLOC_OBJ_L2CACHE
    @ HWLOC_OBJ_L2CACHE
    Level 2 Data (or Unified) Cache.
    Definition: hwloc.h:214
    -
    HWLOC_OBJ_MISC
    @ HWLOC_OBJ_MISC
    Miscellaneous objects (filtered out by default). Objects without particular meaning,...
    Definition: hwloc.h:290
    -
    HWLOC_OBJ_L3CACHE
    @ HWLOC_OBJ_L3CACHE
    Level 3 Data (or Unified) Cache.
    Definition: hwloc.h:215
    -
    HWLOC_OBJ_MACHINE
    @ HWLOC_OBJ_MACHINE
    Machine. A set of processors and memory with cache coherency.
    Definition: hwloc.h:182
    -
    HWLOC_OBJ_OS_DEVICE
    @ HWLOC_OBJ_OS_DEVICE
    Operating system device (filtered out by default).
    Definition: hwloc.h:279
    -
    HWLOC_OBJ_GROUP
    @ HWLOC_OBJ_GROUP
    Group objects. Objects which do not fit in the above but are detected by hwloc and are useful to take...
    Definition: hwloc.h:223
    -
    HWLOC_OBJ_L4CACHE
    @ HWLOC_OBJ_L4CACHE
    Level 4 Data (or Unified) Cache.
    Definition: hwloc.h:216
    -
    HWLOC_OBJ_L1CACHE
    @ HWLOC_OBJ_L1CACHE
    Level 1 Data (or Unified) Cache.
    Definition: hwloc.h:213
    -
    HWLOC_OBJ_PCI_DEVICE
    @ HWLOC_OBJ_PCI_DEVICE
    PCI device (filtered out by default).
    Definition: hwloc.h:269
    -
    HWLOC_OBJ_L5CACHE
    @ HWLOC_OBJ_L5CACHE
    Level 5 Data (or Unified) Cache.
    Definition: hwloc.h:217
    -
    HWLOC_OBJ_BRIDGE
    @ HWLOC_OBJ_BRIDGE
    Bridge (filtered out by default). Any bridge (or PCI switch) that connects the host or an I/O bus,...
    Definition: hwloc.h:257
    -
    HWLOC_OBJ_NUMANODE
    @ HWLOC_OBJ_NUMANODE
    NUMA node. An object that contains memory that is directly and byte-accessible to the host processors...
    Definition: hwloc.h:236
    -
    HWLOC_OBJ_PACKAGE
    @ HWLOC_OBJ_PACKAGE
    Physical package. The physical package that usually gets inserted into a socket on the motherboard....
    Definition: hwloc.h:191
    -
    HWLOC_OBJ_PU
    @ HWLOC_OBJ_PU
    Processing Unit, or (Logical) Processor. An execution unit (may share a core with some other logical ...
    Definition: hwloc.h:201
    -
    HWLOC_OBJ_L3ICACHE
    @ HWLOC_OBJ_L3ICACHE
    Level 3 instruction Cache (filtered out by default).
    Definition: hwloc.h:221
    -
    HWLOC_OBJ_CORE
    @ HWLOC_OBJ_CORE
    Core. A computation unit (may be shared by several PUs, aka logical processors).
    Definition: hwloc.h:197
    -
    HWLOC_OBJ_DIE
    @ HWLOC_OBJ_DIE
    Die within a physical package. A subpart of the physical package, that contains multiple cores.
    Definition: hwloc.h:318
    -
    HWLOC_OBJ_L1ICACHE
    @ HWLOC_OBJ_L1ICACHE
    Level 1 instruction Cache (filtered out by default).
    Definition: hwloc.h:219
    -
    hwloc_obj_t
    struct hwloc_obj * hwloc_obj_t
    Convenience typedef; a pointer to a struct hwloc_obj.
    Definition: hwloc.h:596
    -
    hwloc_topology_init
    int hwloc_topology_init(hwloc_topology_t *topologyp)
    Allocate a topology context.
    -
    hwloc_topology_abi_check
    int hwloc_topology_abi_check(hwloc_topology_t topology)
    Verify that the topology is compatible with the current hwloc library.
    -
    hwloc_topology_dup
    int hwloc_topology_dup(hwloc_topology_t *newtopology, hwloc_topology_t oldtopology)
    Duplicate a topology.
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:692
    -
    hwloc_topology_destroy
    void hwloc_topology_destroy(hwloc_topology_t topology)
    Terminate and free a topology context.
    -
    hwloc_topology_load
    int hwloc_topology_load(hwloc_topology_t topology)
    Build the actual topology.
    -
    hwloc_topology_check
    void hwloc_topology_check(hwloc_topology_t topology)
    Run internal checks on a topology structure.
    -
    hwloc_get_nbobjs_by_depth
    unsigned hwloc_get_nbobjs_by_depth(hwloc_topology_t topology, int depth)
    Returns the width of level at depth depth.
    -
    hwloc_get_root_obj
    static hwloc_obj_t hwloc_get_root_obj(hwloc_topology_t topology)
    Returns the top-object of the topology-tree.
    -
    hwloc_get_obj_by_depth
    hwloc_obj_t hwloc_get_obj_by_depth(hwloc_topology_t topology, int depth, unsigned idx)
    Returns the topology object at logical index idx from depth depth.
    -
    hwloc_get_depth_type
    hwloc_obj_type_t hwloc_get_depth_type(hwloc_topology_t topology, int depth)
    Returns the type of objects at depth depth.
    -
    hwloc_get_obj_by_type
    static hwloc_obj_t hwloc_get_obj_by_type(hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx)
    Returns the topology object at logical index idx with type type.
    -
    hwloc_get_next_obj_by_type
    static hwloc_obj_t hwloc_get_next_obj_by_type(hwloc_topology_t topology, hwloc_obj_type_t type, hwloc_obj_t prev)
    Returns the next object of type type.
    -
    hwloc_get_nbobjs_by_type
    static int hwloc_get_nbobjs_by_type(hwloc_topology_t topology, hwloc_obj_type_t type)
    Returns the width of level type type.
    -
    hwloc_get_type_or_below_depth
    static int hwloc_get_type_or_below_depth(hwloc_topology_t topology, hwloc_obj_type_t type)
    Returns the depth of objects of type type or below.
    -
    hwloc_get_type_or_above_depth
    static int hwloc_get_type_or_above_depth(hwloc_topology_t topology, hwloc_obj_type_t type)
    Returns the depth of objects of type type or above.
    -
    hwloc_get_type_depth
    int hwloc_get_type_depth(hwloc_topology_t topology, hwloc_obj_type_t type)
    Returns the depth of objects of type type.
    -
    hwloc_get_next_obj_by_depth
    static hwloc_obj_t hwloc_get_next_obj_by_depth(hwloc_topology_t topology, int depth, hwloc_obj_t prev)
    Returns the next object at depth depth.
    -
    hwloc_topology_get_depth
    int hwloc_topology_get_depth(hwloc_topology_t restrict topology)
    Get the depth of the hierarchical tree of objects.
    -
    hwloc_get_memory_parents_depth
    int hwloc_get_memory_parents_depth(hwloc_topology_t topology)
    Return the depth of parents where memory objects are attached.
    -
    hwloc_get_type_depth_e
    hwloc_get_type_depth_e
    Definition: hwloc.h:821
    -
    HWLOC_TYPE_DEPTH_UNKNOWN
    @ HWLOC_TYPE_DEPTH_UNKNOWN
    No object of given type exists in the topology.
    Definition: hwloc.h:822
    -
    HWLOC_TYPE_DEPTH_NUMANODE
    @ HWLOC_TYPE_DEPTH_NUMANODE
    Virtual depth for NUMA nodes.
    Definition: hwloc.h:824
    -
    HWLOC_TYPE_DEPTH_MEMCACHE
    @ HWLOC_TYPE_DEPTH_MEMCACHE
    Virtual depth for MemCache object.
    Definition: hwloc.h:829
    -
    HWLOC_TYPE_DEPTH_MISC
    @ HWLOC_TYPE_DEPTH_MISC
    Virtual depth for Misc object.
    Definition: hwloc.h:828
    -
    HWLOC_TYPE_DEPTH_PCI_DEVICE
    @ HWLOC_TYPE_DEPTH_PCI_DEVICE
    Virtual depth for PCI device object level.
    Definition: hwloc.h:826
    -
    HWLOC_TYPE_DEPTH_MULTIPLE
    @ HWLOC_TYPE_DEPTH_MULTIPLE
    Objects of given type exist at different depth in the topology (only for Groups).
    Definition: hwloc.h:823
    -
    HWLOC_TYPE_DEPTH_BRIDGE
    @ HWLOC_TYPE_DEPTH_BRIDGE
    Virtual depth for bridge object level.
    Definition: hwloc.h:825
    -
    HWLOC_TYPE_DEPTH_OS_DEVICE
    @ HWLOC_TYPE_DEPTH_OS_DEVICE
    Virtual depth for software device object level.
    Definition: hwloc.h:827
    -
    hwloc_type_sscanf
    int hwloc_type_sscanf(const char *string, hwloc_obj_type_t *typep, union hwloc_obj_attr_u *attrp, size_t attrsize)
    Return an object type and attributes from a type string.
    -
    hwloc_type_sscanf_as_depth
    int hwloc_type_sscanf_as_depth(const char *string, hwloc_obj_type_t *typep, hwloc_topology_t topology, int *depthp)
    Return an object type and its level depth from a type string.
    -
    hwloc_obj_type_string
    const char * hwloc_obj_type_string(hwloc_obj_type_t type)
    Return a constant stringified object type.
    -
    hwloc_obj_attr_snprintf
    int hwloc_obj_attr_snprintf(char *restrict string, size_t size, hwloc_obj_t obj, const char *restrict separator, int verbose)
    Stringify the attributes of a given topology object into a human-readable form.
    -
    hwloc_obj_type_snprintf
    int hwloc_obj_type_snprintf(char *restrict string, size_t size, hwloc_obj_t obj, int verbose)
    Stringify the type of a given topology object into a human-readable form.
    -
    hwloc_obj_get_info_by_name
    static const char * hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name)
    Search the given key name in object infos and return the corresponding value.
    -
    hwloc_obj_add_info
    int hwloc_obj_add_info(hwloc_obj_t obj, const char *name, const char *value)
    Add the given info name and value pair to the given object.
    -
    hwloc_cpubind_flags_t
    hwloc_cpubind_flags_t
    Process/Thread binding flags.
    Definition: hwloc.h:1155
    -
    hwloc_set_proc_cpubind
    int hwloc_set_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_cpuset_t set, int flags)
    Bind a process pid on CPUs given in physical bitmap set.
    -
    hwloc_set_cpubind
    int hwloc_set_cpubind(hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags)
    Bind current process or thread on CPUs given in physical bitmap set.
    -
    hwloc_get_proc_last_cpu_location
    int hwloc_get_proc_last_cpu_location(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags)
    Get the last physical CPU where a process ran.
    -
    hwloc_get_proc_cpubind
    int hwloc_get_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags)
    Get the current physical binding of process pid.
    -
    hwloc_get_cpubind
    int hwloc_get_cpubind(hwloc_topology_t topology, hwloc_cpuset_t set, int flags)
    Get current process or thread binding.
    -
    hwloc_set_thread_cpubind
    int hwloc_set_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_const_cpuset_t set, int flags)
    Bind a thread thread on CPUs given in physical bitmap set.
    -
    hwloc_get_thread_cpubind
    int hwloc_get_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_cpuset_t set, int flags)
    Get the current physical binding of thread tid.
    -
    hwloc_get_last_cpu_location
    int hwloc_get_last_cpu_location(hwloc_topology_t topology, hwloc_cpuset_t set, int flags)
    Get the last physical CPU where the current process or thread ran.
    -
    HWLOC_CPUBIND_PROCESS
    @ HWLOC_CPUBIND_PROCESS
    Bind all threads of the current (possibly) multithreaded process.
    Definition: hwloc.h:1158
    -
    HWLOC_CPUBIND_NOMEMBIND
    @ HWLOC_CPUBIND_NOMEMBIND
    Avoid any effect on memory binding.
    Definition: hwloc.h:1204
    -
    HWLOC_CPUBIND_STRICT
    @ HWLOC_CPUBIND_STRICT
    Request for strict binding from the OS.
    Definition: hwloc.h:1187
    -
    HWLOC_CPUBIND_THREAD
    @ HWLOC_CPUBIND_THREAD
    Bind current thread of current process.
    Definition: hwloc.h:1162
    -
    hwloc_set_membind
    int hwloc_set_membind(hwloc_topology_t topology, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags)
    Set the default memory binding policy of the current process or thread to prefer the NUMA node(s) spe...
    -
    hwloc_alloc_membind
    void * hwloc_alloc_membind(hwloc_topology_t topology, size_t len, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags)
    Allocate some memory on NUMA memory nodes specified by set.
    -
    hwloc_get_proc_membind
    int hwloc_get_proc_membind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_bitmap_t set, hwloc_membind_policy_t *policy, int flags)
    Query the default memory binding policy and physical locality of the specified process.
    -
    hwloc_free
    int hwloc_free(hwloc_topology_t topology, void *addr, size_t len)
    Free memory that was previously allocated by hwloc_alloc() or hwloc_alloc_membind().
    -
    hwloc_get_area_memlocation
    int hwloc_get_area_memlocation(hwloc_topology_t topology, const void *addr, size_t len, hwloc_bitmap_t set, int flags)
    Get the NUMA nodes where memory identified by (addr, len ) is physically allocated.
    -
    hwloc_alloc
    void * hwloc_alloc(hwloc_topology_t topology, size_t len)
    Allocate some memory.
    -
    hwloc_get_area_membind
    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)
    Query the CPUs near the physical NUMA node(s) and binding policy of the memory identified by (addr,...
    -
    hwloc_membind_flags_t
    hwloc_membind_flags_t
    Memory binding flags.
    Definition: hwloc.h:1461
    -
    hwloc_alloc_membind_policy
    static void * hwloc_alloc_membind_policy(hwloc_topology_t topology, size_t len, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags)
    Allocate some memory on NUMA memory nodes specified by set.
    -
    hwloc_set_proc_membind
    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)
    Set the default memory binding policy of the specified process to prefer the NUMA node(s) specified b...
    -
    hwloc_membind_policy_t
    hwloc_membind_policy_t
    Memory binding policy.
    Definition: hwloc.h:1398
    -
    hwloc_get_membind
    int hwloc_get_membind(hwloc_topology_t topology, hwloc_bitmap_t set, hwloc_membind_policy_t *policy, int flags)
    Query the default memory binding policy and physical locality of the current process or thread.
    -
    hwloc_set_area_membind
    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)
    Bind the already-allocated memory identified by (addr, len) to the NUMA node(s) specified by set.
    -
    HWLOC_MEMBIND_STRICT
    @ HWLOC_MEMBIND_STRICT
    Definition: hwloc.h:1479
    -
    HWLOC_MEMBIND_PROCESS
    @ HWLOC_MEMBIND_PROCESS
    Set policy for all threads of the specified (possibly multithreaded) process. This flag is mutually e...
    Definition: hwloc.h:1466
    -
    HWLOC_MEMBIND_THREAD
    @ HWLOC_MEMBIND_THREAD
    Set policy for a specific thread of the current process. This flag is mutually exclusive with HWLOC_M...
    Definition: hwloc.h:1471
    -
    HWLOC_MEMBIND_BYNODESET
    @ HWLOC_MEMBIND_BYNODESET
    Consider the bitmap argument as a nodeset.
    Definition: hwloc.h:1509
    -
    HWLOC_MEMBIND_MIGRATE
    @ HWLOC_MEMBIND_MIGRATE
    Migrate existing allocated memory. If the memory cannot be migrated and the HWLOC_MEMBIND_STRICT flag...
    Definition: hwloc.h:1485
    -
    HWLOC_MEMBIND_NOCPUBIND
    @ HWLOC_MEMBIND_NOCPUBIND
    Avoid any effect on CPU binding.
    Definition: hwloc.h:1498
    -
    HWLOC_MEMBIND_DEFAULT
    @ HWLOC_MEMBIND_DEFAULT
    Reset the memory allocation policy to the system default. Depending on the operating system,...
    Definition: hwloc.h:1406
    -
    HWLOC_MEMBIND_MIXED
    @ HWLOC_MEMBIND_MIXED
    Returned by get_membind() functions when multiple threads or parts of a memory area have differing me...
    Definition: hwloc.h:1445
    -
    HWLOC_MEMBIND_FIRSTTOUCH
    @ HWLOC_MEMBIND_FIRSTTOUCH
    Allocate each memory page individually on the local NUMA node of the thread that touches it.
    Definition: hwloc.h:1417
    -
    HWLOC_MEMBIND_BIND
    @ HWLOC_MEMBIND_BIND
    Allocate memory on the specified nodes.
    Definition: hwloc.h:1421
    -
    HWLOC_MEMBIND_INTERLEAVE
    @ HWLOC_MEMBIND_INTERLEAVE
    Allocate memory on the given nodes in an interleaved / round-robin manner. The precise layout of the ...
    Definition: hwloc.h:1430
    -
    HWLOC_MEMBIND_NEXTTOUCH
    @ HWLOC_MEMBIND_NEXTTOUCH
    For each page bound with this policy, by next time it is touched (and next time only),...
    Definition: hwloc.h:1437
    -
    hwloc_topology_set_xmlbuffer
    int hwloc_topology_set_xmlbuffer(hwloc_topology_t restrict topology, const char *restrict buffer, int size)
    Enable XML based topology using a memory buffer (instead of a file, as with hwloc_topology_set_xml())...
    -
    hwloc_topology_set_pid
    int hwloc_topology_set_pid(hwloc_topology_t restrict topology, hwloc_pid_t pid)
    Change which process the topology is viewed from.
    -
    hwloc_topology_set_synthetic
    int hwloc_topology_set_synthetic(hwloc_topology_t restrict topology, const char *restrict description)
    Enable synthetic topology.
    -
    hwloc_topology_set_xml
    int hwloc_topology_set_xml(hwloc_topology_t restrict topology, const char *restrict xmlpath)
    Enable XML-file based topology.
    -
    hwloc_topology_components_flag_e
    hwloc_topology_components_flag_e
    Flags to be passed to hwloc_topology_set_components()
    Definition: hwloc.h:1873
    -
    hwloc_topology_set_components
    int hwloc_topology_set_components(hwloc_topology_t restrict topology, unsigned long flags, const char *restrict name)
    Prevent a discovery component from being used for a topology.
    -
    HWLOC_TOPOLOGY_COMPONENTS_FLAG_BLACKLIST
    @ HWLOC_TOPOLOGY_COMPONENTS_FLAG_BLACKLIST
    Blacklist the target component from being used.
    Definition: hwloc.h:1877
    -
    hwloc_topology_get_flags
    unsigned long hwloc_topology_get_flags(hwloc_topology_t topology)
    Get OR'ed flags of a topology.
    -
    hwloc_topology_set_io_types_filter
    int hwloc_topology_set_io_types_filter(hwloc_topology_t topology, enum hwloc_type_filter_e filter)
    Set the filtering for all I/O object types.
    -
    hwloc_topology_get_type_filter
    int hwloc_topology_get_type_filter(hwloc_topology_t topology, hwloc_obj_type_t type, enum hwloc_type_filter_e *filter)
    Get the current filtering for the given object type.
    -
    hwloc_topology_set_userdata
    void hwloc_topology_set_userdata(hwloc_topology_t topology, const void *userdata)
    Set the topology-specific userdata pointer.
    -
    hwloc_topology_set_cache_types_filter
    int hwloc_topology_set_cache_types_filter(hwloc_topology_t topology, enum hwloc_type_filter_e filter)
    Set the filtering for all CPU cache object types.
    -
    hwloc_topology_set_icache_types_filter
    int hwloc_topology_set_icache_types_filter(hwloc_topology_t topology, enum hwloc_type_filter_e filter)
    Set the filtering for all CPU instruction cache object types.
    -
    hwloc_topology_is_thissystem
    int hwloc_topology_is_thissystem(hwloc_topology_t restrict topology)
    Does the topology context come from this system?
    -
    hwloc_topology_get_userdata
    void * hwloc_topology_get_userdata(hwloc_topology_t topology)
    Retrieve the topology-specific userdata pointer.
    -
    hwloc_type_filter_e
    hwloc_type_filter_e
    Type filtering flags.
    Definition: hwloc.h:2254
    -
    hwloc_topology_set_all_types_filter
    int hwloc_topology_set_all_types_filter(hwloc_topology_t topology, enum hwloc_type_filter_e filter)
    Set the filtering for all object types.
    -
    hwloc_topology_set_flags
    int hwloc_topology_set_flags(hwloc_topology_t topology, unsigned long flags)
    Set OR'ed flags to non-yet-loaded topology.
    -
    hwloc_topology_get_support
    const struct hwloc_topology_support * hwloc_topology_get_support(hwloc_topology_t restrict topology)
    Retrieve the topology support.
    -
    hwloc_topology_set_type_filter
    int hwloc_topology_set_type_filter(hwloc_topology_t topology, hwloc_obj_type_t type, enum hwloc_type_filter_e filter)
    Set the filtering for the given object type.
    -
    hwloc_topology_flags_e
    hwloc_topology_flags_e
    Flags to be set onto a topology context before load.
    Definition: hwloc.h:1914
    -
    HWLOC_TYPE_FILTER_KEEP_NONE
    @ HWLOC_TYPE_FILTER_KEEP_NONE
    Ignore all objects of this type.
    Definition: hwloc.h:2268
    -
    HWLOC_TYPE_FILTER_KEEP_IMPORTANT
    @ HWLOC_TYPE_FILTER_KEEP_IMPORTANT
    Only keep likely-important objects of the given type.
    Definition: hwloc.h:2297
    -
    HWLOC_TYPE_FILTER_KEEP_STRUCTURE
    @ HWLOC_TYPE_FILTER_KEEP_STRUCTURE
    Only ignore objects if their entire level does not bring any structure.
    Definition: hwloc.h:2282
    -
    HWLOC_TYPE_FILTER_KEEP_ALL
    @ HWLOC_TYPE_FILTER_KEEP_ALL
    Keep all objects of this type.
    Definition: hwloc.h:2260
    -
    HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED
    @ HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED
    Detect the whole system, ignore reservations, include disallowed objects.
    Definition: hwloc.h:1936
    -
    HWLOC_TOPOLOGY_FLAG_THISSYSTEM_ALLOWED_RESOURCES
    @ HWLOC_TOPOLOGY_FLAG_THISSYSTEM_ALLOWED_RESOURCES
    Get the set of allowed resources from the local operating system even if the topology was loaded from...
    Definition: hwloc.h:1977
    -
    HWLOC_TOPOLOGY_FLAG_NO_CPUKINDS
    @ HWLOC_TOPOLOGY_FLAG_NO_CPUKINDS
    Ignore CPU Kinds.
    Definition: hwloc.h:2082
    -
    HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_MEMBINDING
    @ HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_MEMBINDING
    Do not consider resources outside of the process memory binding.
    Definition: hwloc.h:2048
    -
    HWLOC_TOPOLOGY_FLAG_NO_DISTANCES
    @ HWLOC_TOPOLOGY_FLAG_NO_DISTANCES
    Ignore distances.
    Definition: hwloc.h:2070
    -
    HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM
    @ HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM
    Assume that the selected backend provides the topology for the system on which we are running.
    Definition: hwloc.h:1956
    -
    HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_CPUBINDING
    @ HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_CPUBINDING
    Do not consider resources outside of the process CPU binding.
    Definition: hwloc.h:2026
    -
    HWLOC_TOPOLOGY_FLAG_NO_MEMATTRS
    @ HWLOC_TOPOLOGY_FLAG_NO_MEMATTRS
    Ignore memory attributes.
    Definition: hwloc.h:2076
    -
    HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT
    @ HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT
    Import support from the imported topology.
    Definition: hwloc.h:2001
    -
    HWLOC_TOPOLOGY_FLAG_DONT_CHANGE_BINDING
    @ HWLOC_TOPOLOGY_FLAG_DONT_CHANGE_BINDING
    Do not ever modify the process or thread binding during discovery.
    Definition: hwloc.h:2063
    -
    hwloc_topology_insert_group_object
    hwloc_obj_t hwloc_topology_insert_group_object(hwloc_topology_t topology, hwloc_obj_t group)
    Add more structure to the topology by adding an intermediate Group.
    -
    hwloc_allow_flags_e
    hwloc_allow_flags_e
    Flags to be given to hwloc_topology_allow().
    Definition: hwloc.h:2419
    -
    hwloc_topology_alloc_group_object
    hwloc_obj_t hwloc_topology_alloc_group_object(hwloc_topology_t topology)
    Allocate a Group object to insert later with hwloc_topology_insert_group_object().
    -
    hwloc_topology_refresh
    int hwloc_topology_refresh(hwloc_topology_t topology)
    Refresh internal structures after topology modification.
    -
    hwloc_topology_restrict
    int hwloc_topology_restrict(hwloc_topology_t restrict topology, hwloc_const_bitmap_t set, unsigned long flags)
    Restrict the topology to the given CPU set or nodeset.
    -
    hwloc_restrict_flags_e
    hwloc_restrict_flags_e
    Flags to be given to hwloc_topology_restrict().
    Definition: hwloc.h:2358
    -
    hwloc_obj_add_other_obj_sets
    int hwloc_obj_add_other_obj_sets(hwloc_obj_t dst, hwloc_obj_t src)
    Setup object cpusets/nodesets by OR'ing another object's sets.
    -
    hwloc_topology_insert_misc_object
    hwloc_obj_t hwloc_topology_insert_misc_object(hwloc_topology_t topology, hwloc_obj_t parent, const char *name)
    Add a MISC object as a leaf of the topology.
    -
    hwloc_topology_allow
    int hwloc_topology_allow(hwloc_topology_t restrict topology, hwloc_const_cpuset_t cpuset, hwloc_const_nodeset_t nodeset, unsigned long flags)
    Change the sets of allowed PUs and NUMA nodes in the topology.
    -
    HWLOC_ALLOW_FLAG_CUSTOM
    @ HWLOC_ALLOW_FLAG_CUSTOM
    Allow a custom set of objects, given to hwloc_topology_allow() as cpuset and/or nodeset parameters.
    Definition: hwloc.h:2437
    -
    HWLOC_ALLOW_FLAG_LOCAL_RESTRICTIONS
    @ HWLOC_ALLOW_FLAG_LOCAL_RESTRICTIONS
    Only allow objects that are available to the current process.
    Definition: hwloc.h:2433
    -
    HWLOC_ALLOW_FLAG_ALL
    @ HWLOC_ALLOW_FLAG_ALL
    Mark all objects as allowed in the topology.
    Definition: hwloc.h:2424
    -
    HWLOC_RESTRICT_FLAG_ADAPT_MISC
    @ HWLOC_RESTRICT_FLAG_ADAPT_MISC
    Move Misc objects to ancestors if their parents are removed during restriction. If this flag is not s...
    Definition: hwloc.h:2383
    -
    HWLOC_RESTRICT_FLAG_REMOVE_CPULESS
    @ HWLOC_RESTRICT_FLAG_REMOVE_CPULESS
    Remove all objects that became CPU-less. By default, only objects that contain no PU and no memory ar...
    Definition: hwloc.h:2364
    -
    HWLOC_RESTRICT_FLAG_ADAPT_IO
    @ HWLOC_RESTRICT_FLAG_ADAPT_IO
    Move I/O objects to ancestors if their parents are removed during restriction. If this flag is not se...
    Definition: hwloc.h:2389
    -
    HWLOC_RESTRICT_FLAG_BYNODESET
    @ HWLOC_RESTRICT_FLAG_BYNODESET
    Restrict by nodeset instead of CPU set. Only keep objects whose nodeset is included or partially incl...
    Definition: hwloc.h:2370
    -
    HWLOC_RESTRICT_FLAG_REMOVE_MEMLESS
    @ HWLOC_RESTRICT_FLAG_REMOVE_MEMLESS
    Remove all objects that became Memory-less. By default, only objects that contain no PU and no memory...
    Definition: hwloc.h:2377
    -
    hwloc_bitmap_t
    struct hwloc_bitmap_s * hwloc_bitmap_t
    Set of bits represented as an opaque pointer to an internal bitmap.
    Definition: bitmap.h:68
    -
    hwloc_const_bitmap_t
    const struct hwloc_bitmap_s * hwloc_const_bitmap_t
    a non-modifiable hwloc_bitmap_t
    Definition: bitmap.h:70
    -
    hwloc_obj
    Structure of a topology object.
    Definition: hwloc.h:396
    -
    hwloc_obj::children
    struct hwloc_obj ** children
    Normal children, children[0 .. arity -1].
    Definition: hwloc.h:456
    -
    hwloc_obj::nodeset
    hwloc_nodeset_t nodeset
    NUMA nodes covered by this object or containing this object.
    Definition: hwloc.h:540
    -
    hwloc_obj::logical_index
    unsigned logical_index
    Horizontal index in the whole list of similar objects, hence guaranteed unique across the entire mach...
    Definition: hwloc.h:434
    -
    hwloc_obj::symmetric_subtree
    int symmetric_subtree
    Set if the subtree of normal objects below this object is symmetric, which means all normal children ...
    Definition: hwloc.h:461
    -
    hwloc_obj::misc_arity
    unsigned misc_arity
    Number of Misc children. These children are listed in misc_first_child.
    Definition: hwloc.h:502
    -
    hwloc_obj::depth
    int depth
    Vertical index in the hierarchy.
    Definition: hwloc.h:419
    -
    hwloc_obj::misc_first_child
    struct hwloc_obj * misc_first_child
    First Misc child. Misc objects are listed here (misc_arity and misc_first_child) instead of in the no...
    Definition: hwloc.h:505
    -
    hwloc_obj::subtype
    char * subtype
    Subtype string to better describe the type field.
    Definition: hwloc.h:399
    -
    hwloc_obj::os_index
    unsigned os_index
    OS-provided physical index number. It is not guaranteed unique across the entire machine,...
    Definition: hwloc.h:401
    -
    hwloc_obj::cpuset
    hwloc_cpuset_t cpuset
    CPUs covered by this object.
    Definition: hwloc.h:512
    -
    hwloc_obj::memory_arity
    unsigned memory_arity
    Number of Memory children. These children are listed in memory_first_child.
    Definition: hwloc.h:472
    -
    hwloc_obj::total_memory
    hwloc_uint64_t total_memory
    Total memory (in bytes) in NUMA nodes below this object.
    Definition: hwloc.h:413
    -
    hwloc_obj::userdata
    void * userdata
    Application-given private data pointer, initialized to NULL, use it as you wish. See hwloc_topology_s...
    Definition: hwloc.h:582
    -
    hwloc_obj::io_arity
    unsigned io_arity
    Number of I/O children. These children are listed in io_first_child.
    Definition: hwloc.h:490
    -
    hwloc_obj::prev_sibling
    struct hwloc_obj * prev_sibling
    Previous object below the same parent (inside the same list of children).
    Definition: hwloc.h:449
    -
    hwloc_obj::next_sibling
    struct hwloc_obj * next_sibling
    Next object below the same parent (inside the same list of children).
    Definition: hwloc.h:448
    -
    hwloc_obj::last_child
    struct hwloc_obj * last_child
    Last normal child.
    Definition: hwloc.h:458
    -
    hwloc_obj::next_cousin
    struct hwloc_obj * next_cousin
    Next object of same type and depth.
    Definition: hwloc.h:442
    -
    hwloc_obj::infos
    struct hwloc_info_s * infos
    Array of stringified info type=name.
    Definition: hwloc.h:578
    -
    hwloc_obj::io_first_child
    struct hwloc_obj * io_first_child
    First I/O child. Bridges, PCI and OS devices are listed here (io_arity and io_first_child) instead of...
    Definition: hwloc.h:493
    -
    hwloc_obj::complete_cpuset
    hwloc_cpuset_t complete_cpuset
    The complete CPU set of processors of this object,.
    Definition: hwloc.h:527
    -
    hwloc_obj::gp_index
    hwloc_uint64_t gp_index
    Global persistent index. Generated by hwloc, unique across the topology (contrary to os_index) and pe...
    Definition: hwloc.h:587
    -
    hwloc_obj::infos_count
    unsigned infos_count
    Size of infos array.
    Definition: hwloc.h:579
    -
    hwloc_obj::sibling_rank
    unsigned sibling_rank
    Index in parent's children[] array. Or the index in parent's Memory, I/O or Misc children list.
    Definition: hwloc.h:447
    -
    hwloc_obj::arity
    unsigned arity
    Number of normal children. Memory, Misc and I/O children are not listed here but rather in their dedi...
    Definition: hwloc.h:452
    -
    hwloc_obj::name
    char * name
    Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name str...
    Definition: hwloc.h:408
    -
    hwloc_obj::memory_first_child
    struct hwloc_obj * memory_first_child
    First Memory child. NUMA nodes and Memory-side caches are listed here (memory_arity and memory_first_...
    Definition: hwloc.h:475
    -
    hwloc_obj::complete_nodeset
    hwloc_nodeset_t complete_nodeset
    The complete NUMA node set of this object,.
    Definition: hwloc.h:562
    -
    hwloc_obj::prev_cousin
    struct hwloc_obj * prev_cousin
    Previous object of same type and depth.
    Definition: hwloc.h:443
    -
    hwloc_obj::type
    hwloc_obj_type_t type
    Type of object.
    Definition: hwloc.h:398
    -
    hwloc_obj::attr
    union hwloc_obj_attr_u * attr
    Object type-specific Attributes, may be NULL if no attribute value was found.
    Definition: hwloc.h:415
    -
    hwloc_obj::parent
    struct hwloc_obj * parent
    Parent, NULL if root (Machine object)
    Definition: hwloc.h:446
    -
    hwloc_obj::first_child
    struct hwloc_obj * first_child
    First normal child.
    Definition: hwloc.h:457
    -
    hwloc_obj_attr_u
    Object type-specific Attributes.
    Definition: hwloc.h:599
    -
    hwloc_obj_attr_u::pcidev
    struct hwloc_obj_attr_u::hwloc_pcidev_attr_s pcidev
    -
    hwloc_obj_attr_u::bridge
    struct hwloc_obj_attr_u::hwloc_bridge_attr_s bridge
    -
    hwloc_obj_attr_u::cache
    struct hwloc_obj_attr_u::hwloc_cache_attr_s cache
    -
    hwloc_obj_attr_u::group
    struct hwloc_obj_attr_u::hwloc_group_attr_s group
    -
    hwloc_obj_attr_u::osdev
    struct hwloc_obj_attr_u::hwloc_osdev_attr_s osdev
    -
    hwloc_obj_attr_u::numanode
    struct hwloc_obj_attr_u::hwloc_numanode_attr_s numanode
    -
    hwloc_obj_attr_u::hwloc_numanode_attr_s
    NUMA node-specific Object Attributes.
    Definition: hwloc.h:601
    -
    hwloc_obj_attr_u::hwloc_numanode_attr_s::page_types_len
    unsigned page_types_len
    Size of array page_types.
    Definition: hwloc.h:603
    -
    hwloc_obj_attr_u::hwloc_numanode_attr_s::local_memory
    hwloc_uint64_t local_memory
    Local memory (in bytes)
    Definition: hwloc.h:602
    -
    hwloc_obj_attr_u::hwloc_numanode_attr_s::page_types
    struct hwloc_obj_attr_u::hwloc_numanode_attr_s::hwloc_memory_page_type_s * page_types
    -
    hwloc_obj_attr_u::hwloc_numanode_attr_s::hwloc_memory_page_type_s
    Array of local memory page types, NULL if no local memory and page_types is 0.
    Definition: hwloc.h:609
    -
    hwloc_obj_attr_u::hwloc_numanode_attr_s::hwloc_memory_page_type_s::size
    hwloc_uint64_t size
    Size of pages.
    Definition: hwloc.h:610
    -
    hwloc_obj_attr_u::hwloc_numanode_attr_s::hwloc_memory_page_type_s::count
    hwloc_uint64_t count
    Number of pages of this size.
    Definition: hwloc.h:611
    -
    hwloc_obj_attr_u::hwloc_cache_attr_s
    Cache-specific Object Attributes.
    Definition: hwloc.h:616
    -
    hwloc_obj_attr_u::hwloc_cache_attr_s::depth
    unsigned depth
    Depth of cache (e.g., L1, L2, ...etc.)
    Definition: hwloc.h:618
    -
    hwloc_obj_attr_u::hwloc_cache_attr_s::linesize
    unsigned linesize
    Cache-line size in bytes. 0 if unknown.
    Definition: hwloc.h:619
    -
    hwloc_obj_attr_u::hwloc_cache_attr_s::size
    hwloc_uint64_t size
    Size of cache in bytes.
    Definition: hwloc.h:617
    -
    hwloc_obj_attr_u::hwloc_cache_attr_s::associativity
    int associativity
    Ways of associativity, -1 if fully associative, 0 if unknown.
    Definition: hwloc.h:620
    -
    hwloc_obj_attr_u::hwloc_cache_attr_s::type
    hwloc_obj_cache_type_t type
    Cache type.
    Definition: hwloc.h:622
    -
    hwloc_obj_attr_u::hwloc_group_attr_s
    Group-specific Object Attributes.
    Definition: hwloc.h:625
    -
    hwloc_obj_attr_u::hwloc_group_attr_s::kind
    unsigned kind
    Internally-used kind of group.
    Definition: hwloc.h:628
    -
    hwloc_obj_attr_u::hwloc_group_attr_s::subkind
    unsigned subkind
    Internally-used subkind to distinguish different levels of groups with same kind.
    Definition: hwloc.h:629
    -
    hwloc_obj_attr_u::hwloc_group_attr_s::depth
    unsigned depth
    Depth of group object. It may change if intermediate Group objects are added.
    Definition: hwloc.h:626
    -
    hwloc_obj_attr_u::hwloc_group_attr_s::dont_merge
    unsigned char dont_merge
    Flag preventing groups from being automatically merged with identical parent or children.
    Definition: hwloc.h:630
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s
    PCI Device specific Object Attributes.
    Definition: hwloc.h:633
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::revision
    unsigned char revision
    Definition: hwloc.h:642
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::device_id
    unsigned short device_id
    Definition: hwloc.h:641
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::dev
    unsigned char dev
    Definition: hwloc.h:639
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::subvendor_id
    unsigned short subvendor_id
    Definition: hwloc.h:641
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::linkspeed
    float linkspeed
    Definition: hwloc.h:643
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::func
    unsigned char func
    Definition: hwloc.h:639
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::domain
    unsigned short domain
    Definition: hwloc.h:635
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::vendor_id
    unsigned short vendor_id
    Definition: hwloc.h:641
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::bus
    unsigned char bus
    Definition: hwloc.h:639
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::subdevice_id
    unsigned short subdevice_id
    Definition: hwloc.h:641
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::class_id
    unsigned short class_id
    Definition: hwloc.h:640
    -
    hwloc_obj_attr_u::hwloc_bridge_attr_s
    Bridge specific Object Attributes.
    Definition: hwloc.h:646
    -
    hwloc_obj_attr_u::hwloc_bridge_attr_s::upstream_type
    hwloc_obj_bridge_type_t upstream_type
    Definition: hwloc.h:650
    -
    hwloc_obj_attr_u::hwloc_bridge_attr_s::domain
    unsigned short domain
    Definition: hwloc.h:654
    -
    hwloc_obj_attr_u::hwloc_bridge_attr_s::depth
    unsigned depth
    Definition: hwloc.h:662
    -
    hwloc_obj_attr_u::hwloc_bridge_attr_s::downstream
    union hwloc_obj_attr_u::hwloc_bridge_attr_s::@1 downstream
    -
    hwloc_obj_attr_u::hwloc_bridge_attr_s::pci
    struct hwloc_pcidev_attr_s pci
    Definition: hwloc.h:648
    -
    hwloc_obj_attr_u::hwloc_bridge_attr_s::upstream
    union hwloc_obj_attr_u::hwloc_bridge_attr_s::@0 upstream
    -
    hwloc_obj_attr_u::hwloc_bridge_attr_s::downstream_type
    hwloc_obj_bridge_type_t downstream_type
    Definition: hwloc.h:661
    -
    hwloc_obj_attr_u::hwloc_bridge_attr_s::secondary_bus
    unsigned char secondary_bus
    Definition: hwloc.h:658
    -
    hwloc_obj_attr_u::hwloc_bridge_attr_s::subordinate_bus
    unsigned char subordinate_bus
    Definition: hwloc.h:658
    -
    hwloc_obj_attr_u::hwloc_osdev_attr_s
    OS Device specific Object Attributes.
    Definition: hwloc.h:665
    -
    hwloc_obj_attr_u::hwloc_osdev_attr_s::type
    hwloc_obj_osdev_type_t type
    Definition: hwloc.h:666
    -
    hwloc_info_s
    Object info.
    Definition: hwloc.h:674
    -
    hwloc_info_s::name
    char * name
    Info name.
    Definition: hwloc.h:675
    -
    hwloc_info_s::value
    char * value
    Info value.
    Definition: hwloc.h:676
    -
    hwloc_topology_discovery_support
    Flags describing actual discovery support for this topology.
    Definition: hwloc.h:2119
    -
    hwloc_topology_discovery_support::numa
    unsigned char numa
    Detecting the number of NUMA nodes is supported.
    Definition: hwloc.h:2123
    -
    hwloc_topology_discovery_support::disallowed_numa
    unsigned char disallowed_numa
    Detecting and identifying NUMA nodes that are not available to the current process is supported.
    Definition: hwloc.h:2129
    -
    hwloc_topology_discovery_support::cpukind_efficiency
    unsigned char cpukind_efficiency
    Detecting the efficiency of CPU kinds is supported, see Kinds of CPU cores.
    Definition: hwloc.h:2131
    -
    hwloc_topology_discovery_support::pu
    unsigned char pu
    Detecting the number of PU objects is supported.
    Definition: hwloc.h:2121
    -
    hwloc_topology_discovery_support::numa_memory
    unsigned char numa_memory
    Detecting the amount of memory in NUMA nodes is supported.
    Definition: hwloc.h:2125
    -
    hwloc_topology_discovery_support::disallowed_pu
    unsigned char disallowed_pu
    Detecting and identifying PU objects that are not available to the current process is supported.
    Definition: hwloc.h:2127
    -
    hwloc_topology_cpubind_support
    Flags describing actual PU binding support for this topology.
    Definition: hwloc.h:2139
    -
    hwloc_topology_cpubind_support::get_proc_last_cpu_location
    unsigned char get_proc_last_cpu_location
    Definition: hwloc.h:2159
    -
    hwloc_topology_cpubind_support::set_thread_cpubind
    unsigned char set_thread_cpubind
    Definition: hwloc.h:2153
    -
    hwloc_topology_cpubind_support::set_thisthread_cpubind
    unsigned char set_thisthread_cpubind
    Definition: hwloc.h:2149
    -
    hwloc_topology_cpubind_support::get_thisthread_last_cpu_location
    unsigned char get_thisthread_last_cpu_location
    Definition: hwloc.h:2161
    -
    hwloc_topology_cpubind_support::get_thisproc_cpubind
    unsigned char get_thisproc_cpubind
    Definition: hwloc.h:2143
    -
    hwloc_topology_cpubind_support::get_thisthread_cpubind
    unsigned char get_thisthread_cpubind
    Definition: hwloc.h:2151
    -
    hwloc_topology_cpubind_support::get_thread_cpubind
    unsigned char get_thread_cpubind
    Definition: hwloc.h:2155
    -
    hwloc_topology_cpubind_support::set_thisproc_cpubind
    unsigned char set_thisproc_cpubind
    Definition: hwloc.h:2141
    -
    hwloc_topology_cpubind_support::set_proc_cpubind
    unsigned char set_proc_cpubind
    Definition: hwloc.h:2145
    -
    hwloc_topology_cpubind_support::get_proc_cpubind
    unsigned char get_proc_cpubind
    Definition: hwloc.h:2147
    -
    hwloc_topology_cpubind_support::get_thisproc_last_cpu_location
    unsigned char get_thisproc_last_cpu_location
    Definition: hwloc.h:2157
    -
    hwloc_topology_membind_support
    Flags describing actual memory binding support for this topology.
    Definition: hwloc.h:2169
    -
    hwloc_topology_membind_support::set_thisthread_membind
    unsigned char set_thisthread_membind
    Definition: hwloc.h:2179
    -
    hwloc_topology_membind_support::get_area_membind
    unsigned char get_area_membind
    Definition: hwloc.h:2185
    -
    hwloc_topology_membind_support::firsttouch_membind
    unsigned char firsttouch_membind
    Definition: hwloc.h:2189
    -
    hwloc_topology_membind_support::get_area_memlocation
    unsigned char get_area_memlocation
    Definition: hwloc.h:2199
    -
    hwloc_topology_membind_support::set_thisproc_membind
    unsigned char set_thisproc_membind
    Definition: hwloc.h:2171
    -
    hwloc_topology_membind_support::interleave_membind
    unsigned char interleave_membind
    Definition: hwloc.h:2193
    -
    hwloc_topology_membind_support::get_thisproc_membind
    unsigned char get_thisproc_membind
    Definition: hwloc.h:2173
    -
    hwloc_topology_membind_support::set_area_membind
    unsigned char set_area_membind
    Definition: hwloc.h:2183
    -
    hwloc_topology_membind_support::get_thisthread_membind
    unsigned char get_thisthread_membind
    Definition: hwloc.h:2181
    -
    hwloc_topology_membind_support::set_proc_membind
    unsigned char set_proc_membind
    Definition: hwloc.h:2175
    -
    hwloc_topology_membind_support::get_proc_membind
    unsigned char get_proc_membind
    Definition: hwloc.h:2177
    -
    hwloc_topology_membind_support::migrate_membind
    unsigned char migrate_membind
    Definition: hwloc.h:2197
    -
    hwloc_topology_membind_support::nexttouch_membind
    unsigned char nexttouch_membind
    Definition: hwloc.h:2195
    -
    hwloc_topology_membind_support::alloc_membind
    unsigned char alloc_membind
    Definition: hwloc.h:2187
    -
    hwloc_topology_membind_support::bind_membind
    unsigned char bind_membind
    Definition: hwloc.h:2191
    -
    hwloc_topology_misc_support
    Flags describing miscellaneous features.
    Definition: hwloc.h:2204
    -
    hwloc_topology_misc_support::imported_support
    unsigned char imported_support
    Definition: hwloc.h:2206
    -
    hwloc_topology_support
    Set of flags describing actual support for this topology.
    Definition: hwloc.h:2215
    -
    hwloc_topology_support::misc
    struct hwloc_topology_misc_support * misc
    Definition: hwloc.h:2219
    -
    hwloc_topology_support::membind
    struct hwloc_topology_membind_support * membind
    Definition: hwloc.h:2218
    -
    hwloc_topology_support::cpubind
    struct hwloc_topology_cpubind_support * cpubind
    Definition: hwloc.h:2217
    -
    hwloc_topology_support::discovery
    struct hwloc_topology_discovery_support * discovery
    Definition: hwloc.h:2216
    -
    - - - - - - - - -
    -
    -
    helper.h
    -
    -
    -
    1 /*
    -
    2  * Copyright © 2009 CNRS
    -
    3  * Copyright © 2009-2022 Inria. All rights reserved.
    -
    4  * Copyright © 2009-2012 Université Bordeaux
    -
    5  * Copyright © 2009-2010 Cisco Systems, Inc. All rights reserved.
    -
    6  * See COPYING in top-level directory.
    -
    7  */
    -
    8 
    -
    13 #ifndef HWLOC_HELPER_H
    -
    14 #define HWLOC_HELPER_H
    -
    15 
    -
    16 #ifndef HWLOC_H
    -
    17 #error Please include the main hwloc.h instead
    -
    18 #endif
    -
    19 
    -
    20 #include <stdlib.h>
    -
    21 #include <errno.h>
    -
    22 
    -
    23 
    -
    24 #ifdef __cplusplus
    -
    25 extern "C" {
    -
    26 #endif
    -
    27 
    -
    28 
    -
    41 static __hwloc_inline hwloc_obj_t
    -
    42 hwloc_get_first_largest_obj_inside_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t set)
    -
    43 {
    -
    44  hwloc_obj_t obj = hwloc_get_root_obj(topology);
    -
    45  if (!hwloc_bitmap_intersects(obj->cpuset, set))
    -
    46  return NULL;
    -
    47  while (!hwloc_bitmap_isincluded(obj->cpuset, set)) {
    -
    48  /* while the object intersects without being included, look at its children */
    -
    49  hwloc_obj_t child = obj->first_child;
    -
    50  while (child) {
    -
    51  if (hwloc_bitmap_intersects(child->cpuset, set))
    -
    52  break;
    -
    53  child = child->next_sibling;
    -
    54  }
    -
    55  if (!child)
    -
    56  /* no child intersects, return their father */
    -
    57  return obj;
    -
    58  /* found one intersecting child, look at its children */
    -
    59  obj = child;
    -
    60  }
    -
    61  /* obj is included, return it */
    -
    62  return obj;
    -
    63 }
    -
    64 
    -
    69 HWLOC_DECLSPEC int hwloc_get_largest_objs_inside_cpuset (hwloc_topology_t topology, hwloc_const_cpuset_t set,
    -
    70  hwloc_obj_t * __hwloc_restrict objs, int max);
    -
    71 
    -
    84 static __hwloc_inline hwloc_obj_t
    -
    85 hwloc_get_next_obj_inside_cpuset_by_depth (hwloc_topology_t topology, hwloc_const_cpuset_t set,
    -
    86  int depth, hwloc_obj_t prev)
    -
    87 {
    -
    88  hwloc_obj_t next = hwloc_get_next_obj_by_depth(topology, depth, prev);
    -
    89  if (!next)
    -
    90  return NULL;
    -
    91  while (next && (hwloc_bitmap_iszero(next->cpuset) || !hwloc_bitmap_isincluded(next->cpuset, set)))
    -
    92  next = next->next_cousin;
    -
    93  return next;
    -
    94 }
    -
    95 
    -
    108 static __hwloc_inline hwloc_obj_t
    -
    109 hwloc_get_next_obj_inside_cpuset_by_type (hwloc_topology_t topology, hwloc_const_cpuset_t set,
    -
    110  hwloc_obj_type_t type, hwloc_obj_t prev)
    -
    111 {
    -
    112  int depth = hwloc_get_type_depth(topology, type);
    -
    113  if (depth == HWLOC_TYPE_DEPTH_UNKNOWN || depth == HWLOC_TYPE_DEPTH_MULTIPLE)
    -
    114  return NULL;
    -
    115  return hwloc_get_next_obj_inside_cpuset_by_depth(topology, set, depth, prev);
    -
    116 }
    -
    117 
    -
    126 static __hwloc_inline hwloc_obj_t
    -
    127 hwloc_get_obj_inside_cpuset_by_depth (hwloc_topology_t topology, hwloc_const_cpuset_t set,
    -
    128  int depth, unsigned idx) __hwloc_attribute_pure;
    -
    129 static __hwloc_inline hwloc_obj_t
    -
    130 hwloc_get_obj_inside_cpuset_by_depth (hwloc_topology_t topology, hwloc_const_cpuset_t set,
    -
    131  int depth, unsigned idx)
    -
    132 {
    -
    133  hwloc_obj_t obj = hwloc_get_obj_by_depth (topology, depth, 0);
    -
    134  unsigned count = 0;
    -
    135  if (!obj)
    -
    136  return NULL;
    -
    137  while (obj) {
    -
    138  if (!hwloc_bitmap_iszero(obj->cpuset) && hwloc_bitmap_isincluded(obj->cpuset, set)) {
    -
    139  if (count == idx)
    -
    140  return obj;
    -
    141  count++;
    -
    142  }
    -
    143  obj = obj->next_cousin;
    -
    144  }
    -
    145  return NULL;
    -
    146 }
    -
    147 
    -
    160 static __hwloc_inline hwloc_obj_t
    -
    161 hwloc_get_obj_inside_cpuset_by_type (hwloc_topology_t topology, hwloc_const_cpuset_t set,
    -
    162  hwloc_obj_type_t type, unsigned idx) __hwloc_attribute_pure;
    -
    163 static __hwloc_inline hwloc_obj_t
    -
    164 hwloc_get_obj_inside_cpuset_by_type (hwloc_topology_t topology, hwloc_const_cpuset_t set,
    -
    165  hwloc_obj_type_t type, unsigned idx)
    -
    166 {
    -
    167  int depth = hwloc_get_type_depth(topology, type);
    -
    168  if (depth == HWLOC_TYPE_DEPTH_UNKNOWN || depth == HWLOC_TYPE_DEPTH_MULTIPLE)
    -
    169  return NULL;
    -
    170  return hwloc_get_obj_inside_cpuset_by_depth(topology, set, depth, idx);
    -
    171 }
    -
    172 
    -
    181 static __hwloc_inline unsigned
    -
    182 hwloc_get_nbobjs_inside_cpuset_by_depth (hwloc_topology_t topology, hwloc_const_cpuset_t set,
    -
    183  int depth) __hwloc_attribute_pure;
    -
    184 static __hwloc_inline unsigned
    -
    185 hwloc_get_nbobjs_inside_cpuset_by_depth (hwloc_topology_t topology, hwloc_const_cpuset_t set,
    -
    186  int depth)
    -
    187 {
    -
    188  hwloc_obj_t obj = hwloc_get_obj_by_depth (topology, depth, 0);
    -
    189  unsigned count = 0;
    -
    190  if (!obj)
    -
    191  return 0;
    -
    192  while (obj) {
    -
    193  if (!hwloc_bitmap_iszero(obj->cpuset) && hwloc_bitmap_isincluded(obj->cpuset, set))
    -
    194  count++;
    -
    195  obj = obj->next_cousin;
    -
    196  }
    -
    197  return count;
    -
    198 }
    -
    199 
    -
    212 static __hwloc_inline int
    -
    213 hwloc_get_nbobjs_inside_cpuset_by_type (hwloc_topology_t topology, hwloc_const_cpuset_t set,
    -
    214  hwloc_obj_type_t type) __hwloc_attribute_pure;
    -
    215 static __hwloc_inline int
    -
    216 hwloc_get_nbobjs_inside_cpuset_by_type (hwloc_topology_t topology, hwloc_const_cpuset_t set,
    -
    217  hwloc_obj_type_t type)
    -
    218 {
    -
    219  int depth = hwloc_get_type_depth(topology, type);
    -
    220  if (depth == HWLOC_TYPE_DEPTH_UNKNOWN)
    -
    221  return 0;
    -
    222  if (depth == HWLOC_TYPE_DEPTH_MULTIPLE)
    -
    223  return -1; /* FIXME: agregate nbobjs from different levels? */
    -
    224  return (int) hwloc_get_nbobjs_inside_cpuset_by_depth(topology, set, depth);
    -
    225 }
    -
    226 
    -
    240 static __hwloc_inline int
    -
    241 hwloc_get_obj_index_inside_cpuset (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_const_cpuset_t set,
    -
    242  hwloc_obj_t obj) __hwloc_attribute_pure;
    -
    243 static __hwloc_inline int
    -
    244 hwloc_get_obj_index_inside_cpuset (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_const_cpuset_t set,
    -
    245  hwloc_obj_t obj)
    -
    246 {
    -
    247  int idx = 0;
    -
    248  if (!hwloc_bitmap_isincluded(obj->cpuset, set))
    -
    249  return -1;
    -
    250  /* count how many objects are inside the cpuset on the way from us to the beginning of the level */
    -
    251  while ((obj = obj->prev_cousin) != NULL)
    -
    252  if (!hwloc_bitmap_iszero(obj->cpuset) && hwloc_bitmap_isincluded(obj->cpuset, set))
    -
    253  idx++;
    -
    254  return idx;
    -
    255 }
    -
    256 
    -
    271 static __hwloc_inline hwloc_obj_t
    -
    272 hwloc_get_child_covering_cpuset (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_const_cpuset_t set,
    -
    273  hwloc_obj_t parent) __hwloc_attribute_pure;
    -
    274 static __hwloc_inline hwloc_obj_t
    -
    275 hwloc_get_child_covering_cpuset (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_const_cpuset_t set,
    -
    276  hwloc_obj_t parent)
    -
    277 {
    -
    278  hwloc_obj_t child;
    -
    279  if (hwloc_bitmap_iszero(set))
    -
    280  return NULL;
    -
    281  child = parent->first_child;
    -
    282  while (child) {
    -
    283  if (child->cpuset && hwloc_bitmap_isincluded(set, child->cpuset))
    -
    284  return child;
    -
    285  child = child->next_sibling;
    -
    286  }
    -
    287  return NULL;
    -
    288 }
    -
    289 
    -
    294 static __hwloc_inline hwloc_obj_t
    -
    295 hwloc_get_obj_covering_cpuset (hwloc_topology_t topology, hwloc_const_cpuset_t set) __hwloc_attribute_pure;
    -
    296 static __hwloc_inline hwloc_obj_t
    -
    297 hwloc_get_obj_covering_cpuset (hwloc_topology_t topology, hwloc_const_cpuset_t set)
    -
    298 {
    -
    299  struct hwloc_obj *current = hwloc_get_root_obj(topology);
    -
    300  if (hwloc_bitmap_iszero(set) || !hwloc_bitmap_isincluded(set, current->cpuset))
    -
    301  return NULL;
    -
    302  while (1) {
    -
    303  hwloc_obj_t child = hwloc_get_child_covering_cpuset(topology, set, current);
    -
    304  if (!child)
    -
    305  return current;
    -
    306  current = child;
    -
    307  }
    -
    308 }
    -
    309 
    -
    320 static __hwloc_inline hwloc_obj_t
    -
    321 hwloc_get_next_obj_covering_cpuset_by_depth(hwloc_topology_t topology, hwloc_const_cpuset_t set,
    -
    322  int depth, hwloc_obj_t prev)
    -
    323 {
    -
    324  hwloc_obj_t next = hwloc_get_next_obj_by_depth(topology, depth, prev);
    -
    325  if (!next)
    -
    326  return NULL;
    -
    327  while (next && !hwloc_bitmap_intersects(set, next->cpuset))
    -
    328  next = next->next_cousin;
    -
    329  return next;
    -
    330 }
    -
    331 
    -
    347 static __hwloc_inline hwloc_obj_t
    -
    348 hwloc_get_next_obj_covering_cpuset_by_type(hwloc_topology_t topology, hwloc_const_cpuset_t set,
    -
    349  hwloc_obj_type_t type, hwloc_obj_t prev)
    -
    350 {
    -
    351  int depth = hwloc_get_type_depth(topology, type);
    -
    352  if (depth == HWLOC_TYPE_DEPTH_UNKNOWN || depth == HWLOC_TYPE_DEPTH_MULTIPLE)
    -
    353  return NULL;
    -
    354  return hwloc_get_next_obj_covering_cpuset_by_depth(topology, set, depth, prev);
    -
    355 }
    -
    356 
    -
    377 static __hwloc_inline hwloc_obj_t
    -
    378 hwloc_get_ancestor_obj_by_depth (hwloc_topology_t topology __hwloc_attribute_unused, int depth, hwloc_obj_t obj) __hwloc_attribute_pure;
    -
    379 static __hwloc_inline hwloc_obj_t
    -
    380 hwloc_get_ancestor_obj_by_depth (hwloc_topology_t topology __hwloc_attribute_unused, int depth, hwloc_obj_t obj)
    -
    381 {
    -
    382  hwloc_obj_t ancestor = obj;
    -
    383  if (obj->depth < depth)
    -
    384  return NULL;
    -
    385  while (ancestor && ancestor->depth > depth)
    -
    386  ancestor = ancestor->parent;
    -
    387  return ancestor;
    -
    388 }
    -
    389 
    -
    397 static __hwloc_inline hwloc_obj_t
    -
    398 hwloc_get_ancestor_obj_by_type (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_obj_type_t type, hwloc_obj_t obj) __hwloc_attribute_pure;
    -
    399 static __hwloc_inline hwloc_obj_t
    -
    400 hwloc_get_ancestor_obj_by_type (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_obj_type_t type, hwloc_obj_t obj)
    -
    401 {
    -
    402  hwloc_obj_t ancestor = obj->parent;
    -
    403  while (ancestor && ancestor->type != type)
    -
    404  ancestor = ancestor->parent;
    -
    405  return ancestor;
    -
    406 }
    -
    407 
    -
    409 static __hwloc_inline hwloc_obj_t
    -
    410 hwloc_get_common_ancestor_obj (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_obj_t obj1, hwloc_obj_t obj2) __hwloc_attribute_pure;
    -
    411 static __hwloc_inline hwloc_obj_t
    -
    412 hwloc_get_common_ancestor_obj (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_obj_t obj1, hwloc_obj_t obj2)
    -
    413 {
    -
    414  /* the loop isn't so easy since intermediate ancestors may have
    -
    415  * different depth, causing us to alternate between using obj1->parent
    -
    416  * and obj2->parent. Also, even if at some point we find ancestors of
    -
    417  * of the same depth, their ancestors may have different depth again.
    -
    418  */
    -
    419  while (obj1 != obj2) {
    -
    420  while (obj1->depth > obj2->depth)
    -
    421  obj1 = obj1->parent;
    -
    422  while (obj2->depth > obj1->depth)
    -
    423  obj2 = obj2->parent;
    -
    424  if (obj1 != obj2 && obj1->depth == obj2->depth) {
    -
    425  obj1 = obj1->parent;
    -
    426  obj2 = obj2->parent;
    -
    427  }
    -
    428  }
    -
    429  return obj1;
    -
    430 }
    -
    431 
    -
    437 static __hwloc_inline int
    -
    438 hwloc_obj_is_in_subtree (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_obj_t obj, hwloc_obj_t subtree_root) __hwloc_attribute_pure;
    -
    439 static __hwloc_inline int
    -
    440 hwloc_obj_is_in_subtree (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_obj_t obj, hwloc_obj_t subtree_root)
    -
    441 {
    -
    442  return obj->cpuset && subtree_root->cpuset && hwloc_bitmap_isincluded(obj->cpuset, subtree_root->cpuset);
    -
    443 }
    -
    444 
    -
    455 static __hwloc_inline hwloc_obj_t
    -
    456 hwloc_get_next_child (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_obj_t parent, hwloc_obj_t prev)
    -
    457 {
    -
    458  hwloc_obj_t obj;
    -
    459  int state = 0;
    -
    460  if (prev) {
    -
    461  if (prev->type == HWLOC_OBJ_MISC)
    -
    462  state = 3;
    -
    463  else if (prev->type == HWLOC_OBJ_BRIDGE || prev->type == HWLOC_OBJ_PCI_DEVICE || prev->type == HWLOC_OBJ_OS_DEVICE)
    -
    464  state = 2;
    -
    465  else if (prev->type == HWLOC_OBJ_NUMANODE)
    -
    466  state = 1;
    -
    467  obj = prev->next_sibling;
    -
    468  } else {
    -
    469  obj = parent->first_child;
    -
    470  }
    -
    471  if (!obj && state == 0) {
    -
    472  obj = parent->memory_first_child;
    -
    473  state = 1;
    -
    474  }
    -
    475  if (!obj && state == 1) {
    -
    476  obj = parent->io_first_child;
    -
    477  state = 2;
    -
    478  }
    -
    479  if (!obj && state == 2) {
    -
    480  obj = parent->misc_first_child;
    -
    481  state = 3;
    -
    482  }
    -
    483  return obj;
    -
    484 }
    -
    485 
    -
    512 HWLOC_DECLSPEC int
    -
    513 hwloc_obj_type_is_normal(hwloc_obj_type_t type);
    -
    514 
    -
    523 HWLOC_DECLSPEC int
    -
    524 hwloc_obj_type_is_io(hwloc_obj_type_t type);
    -
    525 
    -
    534 HWLOC_DECLSPEC int
    -
    535 hwloc_obj_type_is_memory(hwloc_obj_type_t type);
    -
    536 
    -
    543 HWLOC_DECLSPEC int
    -
    544 hwloc_obj_type_is_cache(hwloc_obj_type_t type);
    -
    545 
    -
    552 HWLOC_DECLSPEC int
    -
    553 hwloc_obj_type_is_dcache(hwloc_obj_type_t type);
    -
    554 
    -
    561 HWLOC_DECLSPEC int
    -
    562 hwloc_obj_type_is_icache(hwloc_obj_type_t type);
    -
    563 
    -
    593 static __hwloc_inline int
    -
    594 hwloc_get_cache_type_depth (hwloc_topology_t topology,
    -
    595  unsigned cachelevel, hwloc_obj_cache_type_t cachetype)
    -
    596 {
    -
    597  int depth;
    -
    598  int found = HWLOC_TYPE_DEPTH_UNKNOWN;
    -
    599  for (depth=0; ; depth++) {
    -
    600  hwloc_obj_t obj = hwloc_get_obj_by_depth(topology, depth, 0);
    -
    601  if (!obj)
    -
    602  break;
    -
    603  if (!hwloc_obj_type_is_dcache(obj->type) || obj->attr->cache.depth != cachelevel)
    -
    604  /* doesn't match, try next depth */
    -
    605  continue;
    -
    606  if (cachetype == (hwloc_obj_cache_type_t) -1) {
    -
    607  if (found != HWLOC_TYPE_DEPTH_UNKNOWN) {
    -
    608  /* second match, return MULTIPLE */
    -
    609  return HWLOC_TYPE_DEPTH_MULTIPLE;
    -
    610  }
    -
    611  /* first match, mark it as found */
    -
    612  found = depth;
    -
    613  continue;
    -
    614  }
    -
    615  if (obj->attr->cache.type == cachetype || obj->attr->cache.type == HWLOC_OBJ_CACHE_UNIFIED)
    -
    616  /* exact match (either unified is alone, or we match instruction or data), return immediately */
    -
    617  return depth;
    -
    618  }
    -
    619  /* went to the bottom, return what we found */
    -
    620  return found;
    -
    621 }
    -
    622 
    -
    627 static __hwloc_inline hwloc_obj_t
    -
    628 hwloc_get_cache_covering_cpuset (hwloc_topology_t topology, hwloc_const_cpuset_t set) __hwloc_attribute_pure;
    -
    629 static __hwloc_inline hwloc_obj_t
    -
    630 hwloc_get_cache_covering_cpuset (hwloc_topology_t topology, hwloc_const_cpuset_t set)
    -
    631 {
    -
    632  hwloc_obj_t current = hwloc_get_obj_covering_cpuset(topology, set);
    -
    633  while (current) {
    -
    634  if (hwloc_obj_type_is_dcache(current->type))
    -
    635  return current;
    -
    636  current = current->parent;
    -
    637  }
    -
    638  return NULL;
    -
    639 }
    -
    640 
    -
    645 static __hwloc_inline hwloc_obj_t
    -
    646 hwloc_get_shared_cache_covering_obj (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_obj_t obj) __hwloc_attribute_pure;
    -
    647 static __hwloc_inline hwloc_obj_t
    -
    648 hwloc_get_shared_cache_covering_obj (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_obj_t obj)
    -
    649 {
    -
    650  hwloc_obj_t current = obj->parent;
    -
    651  if (!obj->cpuset)
    -
    652  return NULL;
    -
    653  while (current) {
    -
    654  if (!hwloc_bitmap_isequal(current->cpuset, obj->cpuset)
    -
    655  && hwloc_obj_type_is_dcache(current->type))
    -
    656  return current;
    -
    657  current = current->parent;
    -
    658  }
    -
    659  return NULL;
    -
    660 }
    -
    661 
    -
    691 HWLOC_DECLSPEC int hwloc_bitmap_singlify_per_core(hwloc_topology_t topology, hwloc_bitmap_t cpuset, unsigned which);
    -
    692 
    -
    702 static __hwloc_inline hwloc_obj_t
    -
    703 hwloc_get_pu_obj_by_os_index(hwloc_topology_t topology, unsigned os_index) __hwloc_attribute_pure;
    -
    704 static __hwloc_inline hwloc_obj_t
    -
    705 hwloc_get_pu_obj_by_os_index(hwloc_topology_t topology, unsigned os_index)
    -
    706 {
    -
    707  hwloc_obj_t obj = NULL;
    -
    708  while ((obj = hwloc_get_next_obj_by_type(topology, HWLOC_OBJ_PU, obj)) != NULL)
    -
    709  if (obj->os_index == os_index)
    -
    710  return obj;
    -
    711  return NULL;
    -
    712 }
    -
    713 
    -
    723 static __hwloc_inline hwloc_obj_t
    -
    724 hwloc_get_numanode_obj_by_os_index(hwloc_topology_t topology, unsigned os_index) __hwloc_attribute_pure;
    -
    725 static __hwloc_inline hwloc_obj_t
    -
    726 hwloc_get_numanode_obj_by_os_index(hwloc_topology_t topology, unsigned os_index)
    -
    727 {
    -
    728  hwloc_obj_t obj = NULL;
    -
    729  while ((obj = hwloc_get_next_obj_by_type(topology, HWLOC_OBJ_NUMANODE, obj)) != NULL)
    -
    730  if (obj->os_index == os_index)
    -
    731  return obj;
    -
    732  return NULL;
    -
    733 }
    -
    734 
    -
    746 /* TODO: rather provide an iterator? Provide a way to know how much should be allocated? By returning the total number of objects instead? */
    -
    747 HWLOC_DECLSPEC unsigned hwloc_get_closest_objs (hwloc_topology_t topology, hwloc_obj_t src, hwloc_obj_t * __hwloc_restrict objs, unsigned max);
    -
    748 
    -
    761 static __hwloc_inline hwloc_obj_t
    -
    762 hwloc_get_obj_below_by_type (hwloc_topology_t topology,
    -
    763  hwloc_obj_type_t type1, unsigned idx1,
    -
    764  hwloc_obj_type_t type2, unsigned idx2) __hwloc_attribute_pure;
    -
    765 static __hwloc_inline hwloc_obj_t
    -
    766 hwloc_get_obj_below_by_type (hwloc_topology_t topology,
    -
    767  hwloc_obj_type_t type1, unsigned idx1,
    -
    768  hwloc_obj_type_t type2, unsigned idx2)
    -
    769 {
    -
    770  hwloc_obj_t obj;
    -
    771  obj = hwloc_get_obj_by_type (topology, type1, idx1);
    -
    772  if (!obj)
    -
    773  return NULL;
    -
    774  return hwloc_get_obj_inside_cpuset_by_type(topology, obj->cpuset, type2, idx2);
    -
    775 }
    -
    776 
    -
    795 static __hwloc_inline hwloc_obj_t
    -
    796 hwloc_get_obj_below_array_by_type (hwloc_topology_t topology, int nr, hwloc_obj_type_t *typev, unsigned *idxv) __hwloc_attribute_pure;
    -
    797 static __hwloc_inline hwloc_obj_t
    -
    798 hwloc_get_obj_below_array_by_type (hwloc_topology_t topology, int nr, hwloc_obj_type_t *typev, unsigned *idxv)
    -
    799 {
    -
    800  hwloc_obj_t obj = hwloc_get_root_obj(topology);
    -
    801  int i;
    -
    802  for(i=0; i<nr; i++) {
    -
    803  if (!obj)
    -
    804  return NULL;
    -
    805  obj = hwloc_get_obj_inside_cpuset_by_type(topology, obj->cpuset, typev[i], idxv[i]);
    -
    806  }
    -
    807  return obj;
    -
    808 }
    -
    809 
    -
    848 HWLOC_DECLSPEC hwloc_obj_t
    -
    849 hwloc_get_obj_with_same_locality(hwloc_topology_t topology, hwloc_obj_t src,
    -
    850  hwloc_obj_type_t type, const char *subtype, const char *nameprefix,
    -
    851  unsigned long flags);
    -
    852 
    -
    863 enum hwloc_distrib_flags_e {
    -
    867  HWLOC_DISTRIB_FLAG_REVERSE = (1UL<<0)
    -
    868 };
    -
    869 
    -
    890 static __hwloc_inline int
    -
    891 hwloc_distrib(hwloc_topology_t topology,
    -
    892  hwloc_obj_t *roots, unsigned n_roots,
    -
    893  hwloc_cpuset_t *set,
    -
    894  unsigned n,
    -
    895  int until, unsigned long flags)
    -
    896 {
    -
    897  unsigned i;
    -
    898  unsigned tot_weight;
    -
    899  unsigned given, givenweight;
    -
    900  hwloc_cpuset_t *cpusetp = set;
    -
    901 
    -
    902  if (flags & ~HWLOC_DISTRIB_FLAG_REVERSE) {
    -
    903  errno = EINVAL;
    -
    904  return -1;
    -
    905  }
    -
    906 
    -
    907  tot_weight = 0;
    -
    908  for (i = 0; i < n_roots; i++)
    -
    909  tot_weight += (unsigned) hwloc_bitmap_weight(roots[i]->cpuset);
    -
    910 
    -
    911  for (i = 0, given = 0, givenweight = 0; i < n_roots; i++) {
    -
    912  unsigned chunk, weight;
    -
    913  hwloc_obj_t root = roots[flags & HWLOC_DISTRIB_FLAG_REVERSE ? n_roots-1-i : i];
    -
    914  hwloc_cpuset_t cpuset = root->cpuset;
    -
    915  while (!hwloc_obj_type_is_normal(root->type))
    -
    916  /* If memory/io/misc, walk up to normal parent */
    -
    917  root = root->parent;
    -
    918  weight = (unsigned) hwloc_bitmap_weight(cpuset);
    -
    919  if (!weight)
    -
    920  continue;
    -
    921  /* Give to root a chunk proportional to its weight.
    -
    922  * If previous chunks got rounded-up, we may get a bit less. */
    -
    923  chunk = (( (givenweight+weight) * n + tot_weight-1) / tot_weight)
    -
    924  - (( givenweight * n + tot_weight-1) / tot_weight);
    -
    925  if (!root->arity || chunk <= 1 || root->depth >= until) {
    -
    926  /* We can't split any more, put everything there. */
    -
    927  if (chunk) {
    -
    928  /* Fill cpusets with ours */
    -
    929  unsigned j;
    -
    930  for (j=0; j < chunk; j++)
    -
    931  cpusetp[j] = hwloc_bitmap_dup(cpuset);
    -
    932  } else {
    -
    933  /* We got no chunk, just merge our cpuset to a previous one
    -
    934  * (the first chunk cannot be empty)
    -
    935  * so that this root doesn't get ignored.
    -
    936  */
    -
    937  assert(given);
    -
    938  hwloc_bitmap_or(cpusetp[-1], cpusetp[-1], cpuset);
    -
    939  }
    -
    940  } else {
    -
    941  /* Still more to distribute, recurse into children */
    -
    942  hwloc_distrib(topology, root->children, root->arity, cpusetp, chunk, until, flags);
    -
    943  }
    -
    944  cpusetp += chunk;
    -
    945  given += chunk;
    -
    946  givenweight += weight;
    -
    947  }
    -
    948 
    -
    949  return 0;
    -
    950 }
    -
    951 
    -
    969 HWLOC_DECLSPEC hwloc_const_cpuset_t
    -
    970 hwloc_topology_get_complete_cpuset(hwloc_topology_t topology) __hwloc_attribute_pure;
    -
    971 
    -
    983 HWLOC_DECLSPEC hwloc_const_cpuset_t
    -
    984 hwloc_topology_get_topology_cpuset(hwloc_topology_t topology) __hwloc_attribute_pure;
    -
    985 
    -
    1002 HWLOC_DECLSPEC hwloc_const_cpuset_t
    -
    1003 hwloc_topology_get_allowed_cpuset(hwloc_topology_t topology) __hwloc_attribute_pure;
    -
    1004 
    -
    1014 HWLOC_DECLSPEC hwloc_const_nodeset_t
    -
    1015 hwloc_topology_get_complete_nodeset(hwloc_topology_t topology) __hwloc_attribute_pure;
    -
    1016 
    -
    1028 HWLOC_DECLSPEC hwloc_const_nodeset_t
    -
    1029 hwloc_topology_get_topology_nodeset(hwloc_topology_t topology) __hwloc_attribute_pure;
    -
    1030 
    -
    1047 HWLOC_DECLSPEC hwloc_const_nodeset_t
    -
    1048 hwloc_topology_get_allowed_nodeset(hwloc_topology_t topology) __hwloc_attribute_pure;
    -
    1049 
    -
    1070 static __hwloc_inline int
    -
    1071 hwloc_cpuset_to_nodeset(hwloc_topology_t topology, hwloc_const_cpuset_t _cpuset, hwloc_nodeset_t nodeset)
    -
    1072 {
    -
    1073  int depth = hwloc_get_type_depth(topology, HWLOC_OBJ_NUMANODE);
    -
    1074  hwloc_obj_t obj = NULL;
    -
    1075  assert(depth != HWLOC_TYPE_DEPTH_UNKNOWN);
    -
    1076  hwloc_bitmap_zero(nodeset);
    -
    1077  while ((obj = hwloc_get_next_obj_covering_cpuset_by_depth(topology, _cpuset, depth, obj)) != NULL)
    -
    1078  if (hwloc_bitmap_set(nodeset, obj->os_index) < 0)
    -
    1079  return -1;
    -
    1080  return 0;
    -
    1081 }
    -
    1082 
    -
    1094 static __hwloc_inline int
    -
    1095 hwloc_cpuset_from_nodeset(hwloc_topology_t topology, hwloc_cpuset_t _cpuset, hwloc_const_nodeset_t nodeset)
    -
    1096 {
    -
    1097  int depth = hwloc_get_type_depth(topology, HWLOC_OBJ_NUMANODE);
    -
    1098  hwloc_obj_t obj = NULL;
    -
    1099  assert(depth != HWLOC_TYPE_DEPTH_UNKNOWN);
    -
    1100  hwloc_bitmap_zero(_cpuset);
    -
    1101  while ((obj = hwloc_get_next_obj_by_depth(topology, depth, obj)) != NULL) {
    -
    1102  if (hwloc_bitmap_isset(nodeset, obj->os_index))
    -
    1103  /* no need to check obj->cpuset because objects in levels always have a cpuset */
    -
    1104  if (hwloc_bitmap_or(_cpuset, _cpuset, obj->cpuset) < 0)
    -
    1105  return -1;
    -
    1106  }
    -
    1107  return 0;
    -
    1108 }
    -
    1109 
    -
    1129 static __hwloc_inline hwloc_obj_t
    -
    1130 hwloc_get_non_io_ancestor_obj(hwloc_topology_t topology __hwloc_attribute_unused,
    -
    1131  hwloc_obj_t ioobj)
    -
    1132 {
    -
    1133  hwloc_obj_t obj = ioobj;
    -
    1134  while (obj && !obj->cpuset) {
    -
    1135  obj = obj->parent;
    -
    1136  }
    -
    1137  return obj;
    -
    1138 }
    -
    1139 
    -
    1144 static __hwloc_inline hwloc_obj_t
    -
    1145 hwloc_get_next_pcidev(hwloc_topology_t topology, hwloc_obj_t prev)
    -
    1146 {
    -
    1147  return hwloc_get_next_obj_by_type(topology, HWLOC_OBJ_PCI_DEVICE, prev);
    -
    1148 }
    -
    1149 
    -
    1153 static __hwloc_inline hwloc_obj_t
    -
    1154 hwloc_get_pcidev_by_busid(hwloc_topology_t topology,
    -
    1155  unsigned domain, unsigned bus, unsigned dev, unsigned func)
    -
    1156 {
    -
    1157  hwloc_obj_t obj = NULL;
    -
    1158  while ((obj = hwloc_get_next_pcidev(topology, obj)) != NULL) {
    -
    1159  if (obj->attr->pcidev.domain == domain
    -
    1160  && obj->attr->pcidev.bus == bus
    -
    1161  && obj->attr->pcidev.dev == dev
    -
    1162  && obj->attr->pcidev.func == func)
    -
    1163  return obj;
    -
    1164  }
    -
    1165  return NULL;
    -
    1166 }
    -
    1167 
    -
    1171 static __hwloc_inline hwloc_obj_t
    -
    1172 hwloc_get_pcidev_by_busidstring(hwloc_topology_t topology, const char *busid)
    -
    1173 {
    -
    1174  unsigned domain = 0; /* default */
    -
    1175  unsigned bus, dev, func;
    -
    1176 
    -
    1177  if (sscanf(busid, "%x:%x.%x", &bus, &dev, &func) != 3
    -
    1178  && sscanf(busid, "%x:%x:%x.%x", &domain, &bus, &dev, &func) != 4) {
    -
    1179  errno = EINVAL;
    -
    1180  return NULL;
    -
    1181  }
    -
    1182 
    -
    1183  return hwloc_get_pcidev_by_busid(topology, domain, bus, dev, func);
    -
    1184 }
    -
    1185 
    -
    1190 static __hwloc_inline hwloc_obj_t
    -
    1191 hwloc_get_next_osdev(hwloc_topology_t topology, hwloc_obj_t prev)
    -
    1192 {
    -
    1193  return hwloc_get_next_obj_by_type(topology, HWLOC_OBJ_OS_DEVICE, prev);
    -
    1194 }
    -
    1195 
    -
    1200 static __hwloc_inline hwloc_obj_t
    -
    1201 hwloc_get_next_bridge(hwloc_topology_t topology, hwloc_obj_t prev)
    -
    1202 {
    -
    1203  return hwloc_get_next_obj_by_type(topology, HWLOC_OBJ_BRIDGE, prev);
    -
    1204 }
    -
    1205 
    -
    1206 /* \brief Checks whether a given bridge covers a given PCI bus.
    -
    1207  */
    -
    1208 static __hwloc_inline int
    -
    1209 hwloc_bridge_covers_pcibus(hwloc_obj_t bridge,
    -
    1210  unsigned domain, unsigned bus)
    -
    1211 {
    -
    1212  return bridge->type == HWLOC_OBJ_BRIDGE
    -
    1213  && bridge->attr->bridge.downstream_type == HWLOC_OBJ_BRIDGE_PCI
    -
    1214  && bridge->attr->bridge.downstream.pci.domain == domain
    -
    1215  && bridge->attr->bridge.downstream.pci.secondary_bus <= bus
    -
    1216  && bridge->attr->bridge.downstream.pci.subordinate_bus >= bus;
    -
    1217 }
    -
    1218 
    -
    1223 #ifdef __cplusplus
    -
    1224 } /* extern "C" */
    -
    1225 #endif
    -
    1226 
    -
    1227 
    -
    1228 #endif /* HWLOC_HELPER_H */
    -
    hwloc_const_cpuset_t
    hwloc_const_bitmap_t hwloc_const_cpuset_t
    A non-modifiable hwloc_cpuset_t.
    Definition: hwloc.h:142
    -
    hwloc_const_nodeset_t
    hwloc_const_bitmap_t hwloc_const_nodeset_t
    A non-modifiable hwloc_nodeset_t.
    Definition: hwloc.h:160
    -
    hwloc_nodeset_t
    hwloc_bitmap_t hwloc_nodeset_t
    A node set is a bitmap whose bits are set according to NUMA memory node physical OS indexes.
    Definition: hwloc.h:157
    -
    hwloc_cpuset_t
    hwloc_bitmap_t hwloc_cpuset_t
    A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
    Definition: hwloc.h:140
    -
    hwloc_obj_cache_type_t
    enum hwloc_obj_cache_type_e hwloc_obj_cache_type_t
    Cache type.
    -
    hwloc_obj_type_t
    hwloc_obj_type_t
    Type of topology object.
    Definition: hwloc.h:176
    -
    HWLOC_OBJ_BRIDGE_PCI
    @ HWLOC_OBJ_BRIDGE_PCI
    PCI-side of a bridge.
    Definition: hwloc.h:335
    -
    HWLOC_OBJ_CACHE_UNIFIED
    @ HWLOC_OBJ_CACHE_UNIFIED
    Unified cache.
    Definition: hwloc.h:327
    -
    HWLOC_OBJ_MISC
    @ HWLOC_OBJ_MISC
    Miscellaneous objects (filtered out by default). Objects without particular meaning,...
    Definition: hwloc.h:290
    -
    HWLOC_OBJ_OS_DEVICE
    @ HWLOC_OBJ_OS_DEVICE
    Operating system device (filtered out by default).
    Definition: hwloc.h:279
    -
    HWLOC_OBJ_PCI_DEVICE
    @ HWLOC_OBJ_PCI_DEVICE
    PCI device (filtered out by default).
    Definition: hwloc.h:269
    -
    HWLOC_OBJ_BRIDGE
    @ HWLOC_OBJ_BRIDGE
    Bridge (filtered out by default). Any bridge (or PCI switch) that connects the host or an I/O bus,...
    Definition: hwloc.h:257
    -
    HWLOC_OBJ_NUMANODE
    @ HWLOC_OBJ_NUMANODE
    NUMA node. An object that contains memory that is directly and byte-accessible to the host processors...
    Definition: hwloc.h:236
    -
    HWLOC_OBJ_PU
    @ HWLOC_OBJ_PU
    Processing Unit, or (Logical) Processor. An execution unit (may share a core with some other logical ...
    Definition: hwloc.h:201
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:692
    -
    hwloc_get_root_obj
    static hwloc_obj_t hwloc_get_root_obj(hwloc_topology_t topology)
    Returns the top-object of the topology-tree.
    -
    hwloc_get_obj_by_depth
    hwloc_obj_t hwloc_get_obj_by_depth(hwloc_topology_t topology, int depth, unsigned idx)
    Returns the topology object at logical index idx from depth depth.
    -
    hwloc_get_obj_by_type
    static hwloc_obj_t hwloc_get_obj_by_type(hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx)
    Returns the topology object at logical index idx with type type.
    -
    hwloc_get_next_obj_by_type
    static hwloc_obj_t hwloc_get_next_obj_by_type(hwloc_topology_t topology, hwloc_obj_type_t type, hwloc_obj_t prev)
    Returns the next object of type type.
    -
    hwloc_get_type_depth
    int hwloc_get_type_depth(hwloc_topology_t topology, hwloc_obj_type_t type)
    Returns the depth of objects of type type.
    -
    hwloc_get_next_obj_by_depth
    static hwloc_obj_t hwloc_get_next_obj_by_depth(hwloc_topology_t topology, int depth, hwloc_obj_t prev)
    Returns the next object at depth depth.
    -
    HWLOC_TYPE_DEPTH_UNKNOWN
    @ HWLOC_TYPE_DEPTH_UNKNOWN
    No object of given type exists in the topology.
    Definition: hwloc.h:822
    -
    HWLOC_TYPE_DEPTH_MULTIPLE
    @ HWLOC_TYPE_DEPTH_MULTIPLE
    Objects of given type exist at different depth in the topology (only for Groups).
    Definition: hwloc.h:823
    -
    hwloc_get_nbobjs_inside_cpuset_by_type
    static int hwloc_get_nbobjs_inside_cpuset_by_type(hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_type_t type)
    Return the number of objects of type type included in CPU set set.
    Definition: helper.h:216
    -
    hwloc_get_obj_inside_cpuset_by_type
    static hwloc_obj_t hwloc_get_obj_inside_cpuset_by_type(hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_type_t type, unsigned idx)
    Return the idx -th object of type type included in CPU set set.
    Definition: helper.h:164
    -
    hwloc_get_largest_objs_inside_cpuset
    int hwloc_get_largest_objs_inside_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_t *restrict objs, int max)
    Get the set of largest objects covering exactly a given cpuset set.
    -
    hwloc_get_obj_index_inside_cpuset
    static int hwloc_get_obj_index_inside_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_t obj)
    Return the logical index among the objects included in CPU set set.
    Definition: helper.h:244
    -
    hwloc_get_first_largest_obj_inside_cpuset
    static hwloc_obj_t hwloc_get_first_largest_obj_inside_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t set)
    Get the first largest object included in the given cpuset set.
    Definition: helper.h:42
    -
    hwloc_get_next_obj_inside_cpuset_by_depth
    static hwloc_obj_t hwloc_get_next_obj_inside_cpuset_by_depth(hwloc_topology_t topology, hwloc_const_cpuset_t set, int depth, hwloc_obj_t prev)
    Return the next object at depth depth included in CPU set set.
    Definition: helper.h:85
    -
    hwloc_get_nbobjs_inside_cpuset_by_depth
    static unsigned hwloc_get_nbobjs_inside_cpuset_by_depth(hwloc_topology_t topology, hwloc_const_cpuset_t set, int depth)
    Return the number of objects at depth depth included in CPU set set.
    Definition: helper.h:185
    -
    hwloc_get_obj_inside_cpuset_by_depth
    static hwloc_obj_t hwloc_get_obj_inside_cpuset_by_depth(hwloc_topology_t topology, hwloc_const_cpuset_t set, int depth, unsigned idx)
    Return the (logically) idx -th object at depth depth included in CPU set set.
    Definition: helper.h:130
    -
    hwloc_get_next_obj_inside_cpuset_by_type
    static hwloc_obj_t hwloc_get_next_obj_inside_cpuset_by_type(hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_type_t type, hwloc_obj_t prev)
    Return the next object of type type included in CPU set set.
    Definition: helper.h:109
    -
    hwloc_get_child_covering_cpuset
    static hwloc_obj_t hwloc_get_child_covering_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_t parent)
    Get the child covering at least CPU set set.
    Definition: helper.h:275
    -
    hwloc_get_obj_covering_cpuset
    static hwloc_obj_t hwloc_get_obj_covering_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t set)
    Get the lowest object covering at least CPU set set.
    Definition: helper.h:297
    -
    hwloc_get_next_obj_covering_cpuset_by_type
    static hwloc_obj_t hwloc_get_next_obj_covering_cpuset_by_type(hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_type_t type, hwloc_obj_t prev)
    Iterate through same-type objects covering at least CPU set set.
    Definition: helper.h:348
    -
    hwloc_get_next_obj_covering_cpuset_by_depth
    static hwloc_obj_t hwloc_get_next_obj_covering_cpuset_by_depth(hwloc_topology_t topology, hwloc_const_cpuset_t set, int depth, hwloc_obj_t prev)
    Iterate through same-depth objects covering at least CPU set set.
    Definition: helper.h:321
    -
    hwloc_get_next_child
    static hwloc_obj_t hwloc_get_next_child(hwloc_topology_t topology, hwloc_obj_t parent, hwloc_obj_t prev)
    Return the next child.
    Definition: helper.h:456
    -
    hwloc_obj_is_in_subtree
    static int hwloc_obj_is_in_subtree(hwloc_topology_t topology, hwloc_obj_t obj, hwloc_obj_t subtree_root)
    Returns true if obj is inside the subtree beginning with ancestor object subtree_root.
    Definition: helper.h:440
    -
    hwloc_get_ancestor_obj_by_type
    static hwloc_obj_t hwloc_get_ancestor_obj_by_type(hwloc_topology_t topology, hwloc_obj_type_t type, hwloc_obj_t obj)
    Returns the ancestor object of obj with type type.
    Definition: helper.h:400
    -
    hwloc_get_ancestor_obj_by_depth
    static hwloc_obj_t hwloc_get_ancestor_obj_by_depth(hwloc_topology_t topology, int depth, hwloc_obj_t obj)
    Returns the ancestor object of obj at depth depth.
    Definition: helper.h:380
    -
    hwloc_get_common_ancestor_obj
    static hwloc_obj_t hwloc_get_common_ancestor_obj(hwloc_topology_t topology, hwloc_obj_t obj1, hwloc_obj_t obj2)
    Returns the common parent object to objects obj1 and obj2.
    Definition: helper.h:412
    -
    hwloc_obj_type_is_memory
    int hwloc_obj_type_is_memory(hwloc_obj_type_t type)
    Check whether an object type is Memory.
    -
    hwloc_obj_type_is_cache
    int hwloc_obj_type_is_cache(hwloc_obj_type_t type)
    Check whether an object type is a CPU Cache (Data, Unified or Instruction).
    -
    hwloc_obj_type_is_dcache
    int hwloc_obj_type_is_dcache(hwloc_obj_type_t type)
    Check whether an object type is a CPU Data or Unified Cache.
    -
    hwloc_obj_type_is_normal
    int hwloc_obj_type_is_normal(hwloc_obj_type_t type)
    Check whether an object type is Normal.
    -
    hwloc_obj_type_is_icache
    int hwloc_obj_type_is_icache(hwloc_obj_type_t type)
    Check whether an object type is a CPU Instruction Cache,.
    -
    hwloc_obj_type_is_io
    int hwloc_obj_type_is_io(hwloc_obj_type_t type)
    Check whether an object type is I/O.
    -
    hwloc_get_shared_cache_covering_obj
    static hwloc_obj_t hwloc_get_shared_cache_covering_obj(hwloc_topology_t topology, hwloc_obj_t obj)
    Get the first data (or unified) cache shared between an object and somebody else.
    Definition: helper.h:648
    -
    hwloc_get_cache_covering_cpuset
    static hwloc_obj_t hwloc_get_cache_covering_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t set)
    Get the first data (or unified) cache covering a cpuset set.
    Definition: helper.h:630
    -
    hwloc_get_cache_type_depth
    static int hwloc_get_cache_type_depth(hwloc_topology_t topology, unsigned cachelevel, hwloc_obj_cache_type_t cachetype)
    Find the depth of cache objects matching cache level and type.
    Definition: helper.h:594
    -
    hwloc_bitmap_singlify_per_core
    int hwloc_bitmap_singlify_per_core(hwloc_topology_t topology, hwloc_bitmap_t cpuset, unsigned which)
    Remove simultaneous multithreading PUs from a CPU set.
    -
    hwloc_get_closest_objs
    unsigned hwloc_get_closest_objs(hwloc_topology_t topology, hwloc_obj_t src, hwloc_obj_t *restrict objs, unsigned max)
    Do a depth-first traversal of the topology to find and sort.
    -
    hwloc_get_pu_obj_by_os_index
    static hwloc_obj_t hwloc_get_pu_obj_by_os_index(hwloc_topology_t topology, unsigned os_index)
    Returns the object of type HWLOC_OBJ_PU with os_index.
    Definition: helper.h:705
    -
    hwloc_get_obj_below_by_type
    static hwloc_obj_t hwloc_get_obj_below_by_type(hwloc_topology_t topology, hwloc_obj_type_t type1, unsigned idx1, hwloc_obj_type_t type2, unsigned idx2)
    Find an object below another object, both specified by types and indexes.
    Definition: helper.h:766
    -
    hwloc_get_obj_with_same_locality
    hwloc_obj_t hwloc_get_obj_with_same_locality(hwloc_topology_t topology, hwloc_obj_t src, hwloc_obj_type_t type, const char *subtype, const char *nameprefix, unsigned long flags)
    Return an object of a different type with same locality.
    -
    hwloc_get_numanode_obj_by_os_index
    static hwloc_obj_t hwloc_get_numanode_obj_by_os_index(hwloc_topology_t topology, unsigned os_index)
    Returns the object of type HWLOC_OBJ_NUMANODE with os_index.
    Definition: helper.h:726
    -
    hwloc_get_obj_below_array_by_type
    static hwloc_obj_t hwloc_get_obj_below_array_by_type(hwloc_topology_t topology, int nr, hwloc_obj_type_t *typev, unsigned *idxv)
    Find an object below a chain of objects specified by types and indexes.
    Definition: helper.h:798
    -
    hwloc_distrib
    static int hwloc_distrib(hwloc_topology_t topology, hwloc_obj_t *roots, unsigned n_roots, hwloc_cpuset_t *set, unsigned n, int until, unsigned long flags)
    Distribute n items over the topology under roots.
    Definition: helper.h:891
    -
    hwloc_distrib_flags_e
    hwloc_distrib_flags_e
    Flags to be given to hwloc_distrib().
    Definition: helper.h:863
    -
    HWLOC_DISTRIB_FLAG_REVERSE
    @ HWLOC_DISTRIB_FLAG_REVERSE
    Distrib in reverse order, starting from the last objects.
    Definition: helper.h:867
    -
    hwloc_topology_get_allowed_nodeset
    hwloc_const_nodeset_t hwloc_topology_get_allowed_nodeset(hwloc_topology_t topology)
    Get allowed node set.
    -
    hwloc_topology_get_topology_nodeset
    hwloc_const_nodeset_t hwloc_topology_get_topology_nodeset(hwloc_topology_t topology)
    Get topology node set.
    -
    hwloc_topology_get_allowed_cpuset
    hwloc_const_cpuset_t hwloc_topology_get_allowed_cpuset(hwloc_topology_t topology)
    Get allowed CPU set.
    -
    hwloc_topology_get_complete_nodeset
    hwloc_const_nodeset_t hwloc_topology_get_complete_nodeset(hwloc_topology_t topology)
    Get complete node set.
    -
    hwloc_topology_get_topology_cpuset
    hwloc_const_cpuset_t hwloc_topology_get_topology_cpuset(hwloc_topology_t topology)
    Get topology CPU set.
    -
    hwloc_topology_get_complete_cpuset
    hwloc_const_cpuset_t hwloc_topology_get_complete_cpuset(hwloc_topology_t topology)
    Get complete CPU set.
    -
    hwloc_cpuset_to_nodeset
    static int hwloc_cpuset_to_nodeset(hwloc_topology_t topology, hwloc_const_cpuset_t _cpuset, hwloc_nodeset_t nodeset)
    Convert a CPU set into a NUMA node set.
    Definition: helper.h:1071
    -
    hwloc_cpuset_from_nodeset
    static int hwloc_cpuset_from_nodeset(hwloc_topology_t topology, hwloc_cpuset_t _cpuset, hwloc_const_nodeset_t nodeset)
    Convert a NUMA node set into a CPU set.
    Definition: helper.h:1095
    -
    hwloc_bridge_covers_pcibus
    static int hwloc_bridge_covers_pcibus(hwloc_obj_t bridge, unsigned domain, unsigned bus)
    Definition: helper.h:1209
    -
    hwloc_get_pcidev_by_busidstring
    static hwloc_obj_t hwloc_get_pcidev_by_busidstring(hwloc_topology_t topology, const char *busid)
    Find the PCI device object matching the PCI bus id given as a string xxxx:yy:zz.t or yy:zz....
    Definition: helper.h:1172
    -
    hwloc_get_next_pcidev
    static hwloc_obj_t hwloc_get_next_pcidev(hwloc_topology_t topology, hwloc_obj_t prev)
    Get the next PCI device in the system.
    Definition: helper.h:1145
    -
    hwloc_get_next_osdev
    static hwloc_obj_t hwloc_get_next_osdev(hwloc_topology_t topology, hwloc_obj_t prev)
    Get the next OS device in the system.
    Definition: helper.h:1191
    -
    hwloc_get_next_bridge
    static hwloc_obj_t hwloc_get_next_bridge(hwloc_topology_t topology, hwloc_obj_t prev)
    Get the next bridge in the system.
    Definition: helper.h:1201
    -
    hwloc_get_pcidev_by_busid
    static hwloc_obj_t hwloc_get_pcidev_by_busid(hwloc_topology_t topology, unsigned domain, unsigned bus, unsigned dev, unsigned func)
    Find the PCI device object matching the PCI bus id given domain, bus device and function PCI bus id.
    Definition: helper.h:1154
    -
    hwloc_get_non_io_ancestor_obj
    static hwloc_obj_t hwloc_get_non_io_ancestor_obj(hwloc_topology_t topology, hwloc_obj_t ioobj)
    Get the first non-I/O ancestor object.
    Definition: helper.h:1130
    -
    hwloc_bitmap_weight
    int hwloc_bitmap_weight(hwloc_const_bitmap_t bitmap)
    Compute the "weight" of bitmap bitmap (i.e., number of indexes that are in the bitmap).
    -
    hwloc_bitmap_isincluded
    int hwloc_bitmap_isincluded(hwloc_const_bitmap_t sub_bitmap, hwloc_const_bitmap_t super_bitmap)
    Test whether bitmap sub_bitmap is part of bitmap super_bitmap.
    -
    hwloc_bitmap_set
    int hwloc_bitmap_set(hwloc_bitmap_t bitmap, unsigned id)
    Add index id in bitmap bitmap.
    -
    hwloc_bitmap_isset
    int hwloc_bitmap_isset(hwloc_const_bitmap_t bitmap, unsigned id)
    Test whether index id is part of bitmap bitmap.
    -
    hwloc_bitmap_or
    int hwloc_bitmap_or(hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
    Or bitmaps bitmap1 and bitmap2 and store the result in bitmap res.
    -
    hwloc_bitmap_isequal
    int hwloc_bitmap_isequal(hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
    Test whether bitmap bitmap1 is equal to bitmap bitmap2.
    -
    hwloc_bitmap_iszero
    int hwloc_bitmap_iszero(hwloc_const_bitmap_t bitmap)
    Test whether bitmap bitmap is empty.
    -
    hwloc_bitmap_t
    struct hwloc_bitmap_s * hwloc_bitmap_t
    Set of bits represented as an opaque pointer to an internal bitmap.
    Definition: bitmap.h:68
    -
    hwloc_bitmap_zero
    void hwloc_bitmap_zero(hwloc_bitmap_t bitmap)
    Empty the bitmap bitmap.
    -
    hwloc_bitmap_dup
    hwloc_bitmap_t hwloc_bitmap_dup(hwloc_const_bitmap_t bitmap)
    Duplicate bitmap bitmap by allocating a new bitmap and copying bitmap contents.
    -
    hwloc_bitmap_intersects
    int hwloc_bitmap_intersects(hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
    Test whether bitmaps bitmap1 and bitmap2 intersects.
    -
    hwloc_obj
    Structure of a topology object.
    Definition: hwloc.h:396
    -
    hwloc_obj::children
    struct hwloc_obj ** children
    Normal children, children[0 .. arity -1].
    Definition: hwloc.h:456
    -
    hwloc_obj::nodeset
    hwloc_nodeset_t nodeset
    NUMA nodes covered by this object or containing this object.
    Definition: hwloc.h:540
    -
    hwloc_obj::depth
    int depth
    Vertical index in the hierarchy.
    Definition: hwloc.h:419
    -
    hwloc_obj::misc_first_child
    struct hwloc_obj * misc_first_child
    First Misc child. Misc objects are listed here (misc_arity and misc_first_child) instead of in the no...
    Definition: hwloc.h:505
    -
    hwloc_obj::subtype
    char * subtype
    Subtype string to better describe the type field.
    Definition: hwloc.h:399
    -
    hwloc_obj::os_index
    unsigned os_index
    OS-provided physical index number. It is not guaranteed unique across the entire machine,...
    Definition: hwloc.h:401
    -
    hwloc_obj::cpuset
    hwloc_cpuset_t cpuset
    CPUs covered by this object.
    Definition: hwloc.h:512
    -
    hwloc_obj::next_sibling
    struct hwloc_obj * next_sibling
    Next object below the same parent (inside the same list of children).
    Definition: hwloc.h:448
    -
    hwloc_obj::next_cousin
    struct hwloc_obj * next_cousin
    Next object of same type and depth.
    Definition: hwloc.h:442
    -
    hwloc_obj::io_first_child
    struct hwloc_obj * io_first_child
    First I/O child. Bridges, PCI and OS devices are listed here (io_arity and io_first_child) instead of...
    Definition: hwloc.h:493
    -
    hwloc_obj::arity
    unsigned arity
    Number of normal children. Memory, Misc and I/O children are not listed here but rather in their dedi...
    Definition: hwloc.h:452
    -
    hwloc_obj::memory_first_child
    struct hwloc_obj * memory_first_child
    First Memory child. NUMA nodes and Memory-side caches are listed here (memory_arity and memory_first_...
    Definition: hwloc.h:475
    -
    hwloc_obj::prev_cousin
    struct hwloc_obj * prev_cousin
    Previous object of same type and depth.
    Definition: hwloc.h:443
    -
    hwloc_obj::type
    hwloc_obj_type_t type
    Type of object.
    Definition: hwloc.h:398
    -
    hwloc_obj::attr
    union hwloc_obj_attr_u * attr
    Object type-specific Attributes, may be NULL if no attribute value was found.
    Definition: hwloc.h:415
    -
    hwloc_obj::parent
    struct hwloc_obj * parent
    Parent, NULL if root (Machine object)
    Definition: hwloc.h:446
    -
    hwloc_obj::first_child
    struct hwloc_obj * first_child
    First normal child.
    Definition: hwloc.h:457
    -
    hwloc_obj_attr_u::pcidev
    struct hwloc_obj_attr_u::hwloc_pcidev_attr_s pcidev
    -
    hwloc_obj_attr_u::bridge
    struct hwloc_obj_attr_u::hwloc_bridge_attr_s bridge
    -
    hwloc_obj_attr_u::cache
    struct hwloc_obj_attr_u::hwloc_cache_attr_s cache
    -
    hwloc_obj_attr_u::hwloc_cache_attr_s::depth
    unsigned depth
    Depth of cache (e.g., L1, L2, ...etc.)
    Definition: hwloc.h:618
    -
    hwloc_obj_attr_u::hwloc_cache_attr_s::type
    hwloc_obj_cache_type_t type
    Cache type.
    Definition: hwloc.h:622
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::dev
    unsigned char dev
    Definition: hwloc.h:639
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::func
    unsigned char func
    Definition: hwloc.h:639
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::domain
    unsigned short domain
    Definition: hwloc.h:635
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::bus
    unsigned char bus
    Definition: hwloc.h:639
    -
    hwloc_obj_attr_u::hwloc_bridge_attr_s::downstream
    union hwloc_obj_attr_u::hwloc_bridge_attr_s::@1 downstream
    -
    hwloc_obj_attr_u::hwloc_bridge_attr_s::pci
    struct hwloc_pcidev_attr_s pci
    Definition: hwloc.h:648
    -
    hwloc_obj_attr_u::hwloc_bridge_attr_s::downstream_type
    hwloc_obj_bridge_type_t downstream_type
    Definition: hwloc.h:661
    -
    - - - - - - - - -
    -
    -
    bitmap.h
    -
    -
    -
    1 /*
    -
    2  * Copyright © 2009 CNRS
    -
    3  * Copyright © 2009-2022 Inria. All rights reserved.
    -
    4  * Copyright © 2009-2012 Université Bordeaux
    -
    5  * Copyright © 2009-2011 Cisco Systems, Inc. All rights reserved.
    -
    6  * See COPYING in top-level directory.
    -
    7  */
    -
    8 
    -
    13 #ifndef HWLOC_BITMAP_H
    -
    14 #define HWLOC_BITMAP_H
    -
    15 
    -
    16 #include "hwloc/autogen/config.h"
    -
    17 
    -
    18 #include <assert.h>
    -
    19 
    -
    20 
    -
    21 #ifdef __cplusplus
    -
    22 extern "C" {
    -
    23 #endif
    -
    24 
    -
    25 
    -
    68 typedef struct hwloc_bitmap_s * hwloc_bitmap_t;
    -
    70 typedef const struct hwloc_bitmap_s * hwloc_const_bitmap_t;
    -
    71 
    -
    72 
    -
    73 /*
    -
    74  * Bitmap allocation, freeing and copying.
    -
    75  */
    -
    76 
    -
    84 HWLOC_DECLSPEC hwloc_bitmap_t hwloc_bitmap_alloc(void) __hwloc_attribute_malloc;
    -
    85 
    -
    87 HWLOC_DECLSPEC hwloc_bitmap_t hwloc_bitmap_alloc_full(void) __hwloc_attribute_malloc;
    -
    88 
    -
    93 HWLOC_DECLSPEC void hwloc_bitmap_free(hwloc_bitmap_t bitmap);
    -
    94 
    -
    99 HWLOC_DECLSPEC hwloc_bitmap_t hwloc_bitmap_dup(hwloc_const_bitmap_t bitmap) __hwloc_attribute_malloc;
    -
    100 
    -
    102 HWLOC_DECLSPEC int hwloc_bitmap_copy(hwloc_bitmap_t dst, hwloc_const_bitmap_t src);
    -
    103 
    -
    104 
    -
    105 /*
    -
    106  * Bitmap/String Conversion
    -
    107  */
    -
    108 
    -
    118 HWLOC_DECLSPEC int hwloc_bitmap_snprintf(char * __hwloc_restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap);
    -
    119 
    -
    124 HWLOC_DECLSPEC int hwloc_bitmap_asprintf(char ** strp, hwloc_const_bitmap_t bitmap);
    -
    125 
    -
    128 HWLOC_DECLSPEC int hwloc_bitmap_sscanf(hwloc_bitmap_t bitmap, const char * __hwloc_restrict string);
    -
    129 
    -
    143 HWLOC_DECLSPEC int hwloc_bitmap_list_snprintf(char * __hwloc_restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap);
    -
    144 
    -
    149 HWLOC_DECLSPEC int hwloc_bitmap_list_asprintf(char ** strp, hwloc_const_bitmap_t bitmap);
    -
    150 
    -
    153 HWLOC_DECLSPEC int hwloc_bitmap_list_sscanf(hwloc_bitmap_t bitmap, const char * __hwloc_restrict string);
    -
    154 
    -
    167 HWLOC_DECLSPEC int hwloc_bitmap_taskset_snprintf(char * __hwloc_restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap);
    -
    168 
    -
    173 HWLOC_DECLSPEC int hwloc_bitmap_taskset_asprintf(char ** strp, hwloc_const_bitmap_t bitmap);
    -
    174 
    -
    177 HWLOC_DECLSPEC int hwloc_bitmap_taskset_sscanf(hwloc_bitmap_t bitmap, const char * __hwloc_restrict string);
    -
    178 
    -
    179 
    -
    180 /*
    -
    181  * Building bitmaps.
    -
    182  */
    -
    183 
    -
    185 HWLOC_DECLSPEC void hwloc_bitmap_zero(hwloc_bitmap_t bitmap);
    -
    186 
    -
    188 HWLOC_DECLSPEC void hwloc_bitmap_fill(hwloc_bitmap_t bitmap);
    -
    189 
    -
    191 HWLOC_DECLSPEC int hwloc_bitmap_only(hwloc_bitmap_t bitmap, unsigned id);
    -
    192 
    -
    194 HWLOC_DECLSPEC int hwloc_bitmap_allbut(hwloc_bitmap_t bitmap, unsigned id);
    -
    195 
    -
    197 HWLOC_DECLSPEC int hwloc_bitmap_from_ulong(hwloc_bitmap_t bitmap, unsigned long mask);
    -
    198 
    -
    200 HWLOC_DECLSPEC int hwloc_bitmap_from_ith_ulong(hwloc_bitmap_t bitmap, unsigned i, unsigned long mask);
    -
    201 
    -
    203 HWLOC_DECLSPEC int hwloc_bitmap_from_ulongs(hwloc_bitmap_t bitmap, unsigned nr, const unsigned long *masks);
    -
    204 
    -
    205 
    -
    206 /*
    -
    207  * Modifying bitmaps.
    -
    208  */
    -
    209 
    -
    211 HWLOC_DECLSPEC int hwloc_bitmap_set(hwloc_bitmap_t bitmap, unsigned id);
    -
    212 
    -
    217 HWLOC_DECLSPEC int hwloc_bitmap_set_range(hwloc_bitmap_t bitmap, unsigned begin, int end);
    -
    218 
    -
    220 HWLOC_DECLSPEC int hwloc_bitmap_set_ith_ulong(hwloc_bitmap_t bitmap, unsigned i, unsigned long mask);
    -
    221 
    -
    223 HWLOC_DECLSPEC int hwloc_bitmap_clr(hwloc_bitmap_t bitmap, unsigned id);
    -
    224 
    -
    229 HWLOC_DECLSPEC int hwloc_bitmap_clr_range(hwloc_bitmap_t bitmap, unsigned begin, int end);
    -
    230 
    -
    250 HWLOC_DECLSPEC int hwloc_bitmap_singlify(hwloc_bitmap_t bitmap);
    -
    251 
    -
    252 
    -
    253 /*
    -
    254  * Consulting bitmaps.
    -
    255  */
    -
    256 
    -
    258 HWLOC_DECLSPEC unsigned long hwloc_bitmap_to_ulong(hwloc_const_bitmap_t bitmap) __hwloc_attribute_pure;
    -
    259 
    -
    261 HWLOC_DECLSPEC unsigned long hwloc_bitmap_to_ith_ulong(hwloc_const_bitmap_t bitmap, unsigned i) __hwloc_attribute_pure;
    -
    262 
    -
    269 HWLOC_DECLSPEC int hwloc_bitmap_to_ulongs(hwloc_const_bitmap_t bitmap, unsigned nr, unsigned long *masks);
    -
    270 
    -
    284 HWLOC_DECLSPEC int hwloc_bitmap_nr_ulongs(hwloc_const_bitmap_t bitmap) __hwloc_attribute_pure;
    -
    285 
    -
    290 HWLOC_DECLSPEC int hwloc_bitmap_isset(hwloc_const_bitmap_t bitmap, unsigned id) __hwloc_attribute_pure;
    -
    291 
    -
    296 HWLOC_DECLSPEC int hwloc_bitmap_iszero(hwloc_const_bitmap_t bitmap) __hwloc_attribute_pure;
    -
    297 
    -
    304 HWLOC_DECLSPEC int hwloc_bitmap_isfull(hwloc_const_bitmap_t bitmap) __hwloc_attribute_pure;
    -
    305 
    -
    310 HWLOC_DECLSPEC int hwloc_bitmap_first(hwloc_const_bitmap_t bitmap) __hwloc_attribute_pure;
    -
    311 
    -
    318 HWLOC_DECLSPEC int hwloc_bitmap_next(hwloc_const_bitmap_t bitmap, int prev) __hwloc_attribute_pure;
    -
    319 
    -
    324 HWLOC_DECLSPEC int hwloc_bitmap_last(hwloc_const_bitmap_t bitmap) __hwloc_attribute_pure;
    -
    325 
    -
    333 HWLOC_DECLSPEC int hwloc_bitmap_weight(hwloc_const_bitmap_t bitmap) __hwloc_attribute_pure;
    -
    334 
    -
    339 HWLOC_DECLSPEC int hwloc_bitmap_first_unset(hwloc_const_bitmap_t bitmap) __hwloc_attribute_pure;
    -
    340 
    -
    347 HWLOC_DECLSPEC int hwloc_bitmap_next_unset(hwloc_const_bitmap_t bitmap, int prev) __hwloc_attribute_pure;
    -
    348 
    -
    353 HWLOC_DECLSPEC int hwloc_bitmap_last_unset(hwloc_const_bitmap_t bitmap) __hwloc_attribute_pure;
    -
    354 
    -
    370 #define hwloc_bitmap_foreach_begin(id, bitmap) \
    -
    371 do { \
    -
    372  assert(hwloc_bitmap_weight(bitmap) != -1); \
    -
    373  for (id = hwloc_bitmap_first(bitmap); \
    -
    374  (unsigned) id != (unsigned) -1; \
    -
    375  id = hwloc_bitmap_next(bitmap, id)) {
    -
    376 
    -
    384 #define hwloc_bitmap_foreach_end() \
    -
    385  } \
    -
    386 } while (0)
    -
    387 
    -
    388 
    -
    389 /*
    -
    390  * Combining bitmaps.
    -
    391  */
    -
    392 
    -
    397 HWLOC_DECLSPEC int hwloc_bitmap_or (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2);
    -
    398 
    -
    403 HWLOC_DECLSPEC int hwloc_bitmap_and (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2);
    -
    404 
    -
    409 HWLOC_DECLSPEC int hwloc_bitmap_andnot (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2);
    -
    410 
    -
    415 HWLOC_DECLSPEC int hwloc_bitmap_xor (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2);
    -
    416 
    -
    421 HWLOC_DECLSPEC int hwloc_bitmap_not (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap);
    -
    422 
    -
    423 
    -
    424 /*
    -
    425  * Comparing bitmaps.
    -
    426  */
    -
    427 
    -
    432 HWLOC_DECLSPEC int hwloc_bitmap_intersects (hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2) __hwloc_attribute_pure;
    -
    433 
    -
    440 HWLOC_DECLSPEC int hwloc_bitmap_isincluded (hwloc_const_bitmap_t sub_bitmap, hwloc_const_bitmap_t super_bitmap) __hwloc_attribute_pure;
    -
    441 
    -
    446 HWLOC_DECLSPEC int hwloc_bitmap_isequal (hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2) __hwloc_attribute_pure;
    -
    447 
    -
    465 HWLOC_DECLSPEC int hwloc_bitmap_compare_first(hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2) __hwloc_attribute_pure;
    -
    466 
    -
    484 HWLOC_DECLSPEC int hwloc_bitmap_compare(hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2) __hwloc_attribute_pure;
    -
    485 
    -
    489 #ifdef __cplusplus
    -
    490 } /* extern "C" */
    -
    491 #endif
    -
    492 
    -
    493 
    -
    494 #endif /* HWLOC_BITMAP_H */
    -
    hwloc_bitmap_weight
    int hwloc_bitmap_weight(hwloc_const_bitmap_t bitmap)
    Compute the "weight" of bitmap bitmap (i.e., number of indexes that are in the bitmap).
    -
    hwloc_bitmap_alloc_full
    hwloc_bitmap_t hwloc_bitmap_alloc_full(void)
    Allocate a new full bitmap.
    -
    hwloc_bitmap_isincluded
    int hwloc_bitmap_isincluded(hwloc_const_bitmap_t sub_bitmap, hwloc_const_bitmap_t super_bitmap)
    Test whether bitmap sub_bitmap is part of bitmap super_bitmap.
    -
    hwloc_bitmap_set
    int hwloc_bitmap_set(hwloc_bitmap_t bitmap, unsigned id)
    Add index id in bitmap bitmap.
    -
    hwloc_bitmap_sscanf
    int hwloc_bitmap_sscanf(hwloc_bitmap_t bitmap, const char *restrict string)
    Parse a bitmap string and stores it in bitmap bitmap.
    -
    hwloc_bitmap_allbut
    int hwloc_bitmap_allbut(hwloc_bitmap_t bitmap, unsigned id)
    Fill the bitmap and clear the index id.
    -
    hwloc_bitmap_fill
    void hwloc_bitmap_fill(hwloc_bitmap_t bitmap)
    Fill bitmap bitmap with all possible indexes (even if those objects don't exist or are otherwise unav...
    -
    hwloc_bitmap_asprintf
    int hwloc_bitmap_asprintf(char **strp, hwloc_const_bitmap_t bitmap)
    Stringify a bitmap into a newly allocated string.
    -
    hwloc_bitmap_only
    int hwloc_bitmap_only(hwloc_bitmap_t bitmap, unsigned id)
    Empty the bitmap bitmap and add bit id.
    -
    hwloc_bitmap_isset
    int hwloc_bitmap_isset(hwloc_const_bitmap_t bitmap, unsigned id)
    Test whether index id is part of bitmap bitmap.
    -
    hwloc_bitmap_or
    int hwloc_bitmap_or(hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
    Or bitmaps bitmap1 and bitmap2 and store the result in bitmap res.
    -
    hwloc_bitmap_compare
    int hwloc_bitmap_compare(hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
    Compare bitmaps bitmap1 and bitmap2 in lexicographic order.
    -
    hwloc_bitmap_free
    void hwloc_bitmap_free(hwloc_bitmap_t bitmap)
    Free bitmap bitmap.
    -
    hwloc_bitmap_xor
    int hwloc_bitmap_xor(hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
    Xor bitmaps bitmap1 and bitmap2 and store the result in bitmap res.
    -
    hwloc_bitmap_isequal
    int hwloc_bitmap_isequal(hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
    Test whether bitmap bitmap1 is equal to bitmap bitmap2.
    -
    hwloc_bitmap_taskset_asprintf
    int hwloc_bitmap_taskset_asprintf(char **strp, hwloc_const_bitmap_t bitmap)
    Stringify a bitmap into a newly allocated taskset-specific string.
    -
    hwloc_bitmap_list_asprintf
    int hwloc_bitmap_list_asprintf(char **strp, hwloc_const_bitmap_t bitmap)
    Stringify a bitmap into a newly allocated list string.
    -
    hwloc_bitmap_list_snprintf
    int hwloc_bitmap_list_snprintf(char *restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap)
    Stringify a bitmap in the list format.
    -
    hwloc_bitmap_last
    int hwloc_bitmap_last(hwloc_const_bitmap_t bitmap)
    Compute the last index (most significant bit) in bitmap bitmap.
    -
    hwloc_bitmap_set_ith_ulong
    int hwloc_bitmap_set_ith_ulong(hwloc_bitmap_t bitmap, unsigned i, unsigned long mask)
    Replace i -th subset of bitmap bitmap with unsigned long mask.
    -
    hwloc_bitmap_first
    int hwloc_bitmap_first(hwloc_const_bitmap_t bitmap)
    Compute the first index (least significant bit) in bitmap bitmap.
    -
    hwloc_bitmap_last_unset
    int hwloc_bitmap_last_unset(hwloc_const_bitmap_t bitmap)
    Compute the last unset index (most significant bit) in bitmap bitmap.
    -
    hwloc_bitmap_from_ith_ulong
    int hwloc_bitmap_from_ith_ulong(hwloc_bitmap_t bitmap, unsigned i, unsigned long mask)
    Setup bitmap bitmap from unsigned long mask used as i -th subset.
    -
    hwloc_bitmap_taskset_sscanf
    int hwloc_bitmap_taskset_sscanf(hwloc_bitmap_t bitmap, const char *restrict string)
    Parse a taskset-specific bitmap string and stores it in bitmap bitmap.
    -
    hwloc_bitmap_iszero
    int hwloc_bitmap_iszero(hwloc_const_bitmap_t bitmap)
    Test whether bitmap bitmap is empty.
    -
    hwloc_bitmap_taskset_snprintf
    int hwloc_bitmap_taskset_snprintf(char *restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap)
    Stringify a bitmap in the taskset-specific format.
    -
    hwloc_bitmap_isfull
    int hwloc_bitmap_isfull(hwloc_const_bitmap_t bitmap)
    Test whether bitmap bitmap is completely full.
    -
    hwloc_bitmap_and
    int hwloc_bitmap_and(hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
    And bitmaps bitmap1 and bitmap2 and store the result in bitmap res.
    -
    hwloc_bitmap_copy
    int hwloc_bitmap_copy(hwloc_bitmap_t dst, hwloc_const_bitmap_t src)
    Copy the contents of bitmap src into the already allocated bitmap dst.
    -
    hwloc_bitmap_andnot
    int hwloc_bitmap_andnot(hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
    And bitmap bitmap1 and the negation of bitmap2 and store the result in bitmap res.
    -
    hwloc_bitmap_clr_range
    int hwloc_bitmap_clr_range(hwloc_bitmap_t bitmap, unsigned begin, int end)
    Remove indexes from begin to end in bitmap bitmap.
    -
    hwloc_bitmap_not
    int hwloc_bitmap_not(hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap)
    Negate bitmap bitmap and store the result in bitmap res.
    -
    hwloc_bitmap_snprintf
    int hwloc_bitmap_snprintf(char *restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap)
    Stringify a bitmap.
    -
    hwloc_bitmap_next_unset
    int hwloc_bitmap_next_unset(hwloc_const_bitmap_t bitmap, int prev)
    Compute the next unset index in bitmap bitmap which is after index prev.
    -
    hwloc_bitmap_set_range
    int hwloc_bitmap_set_range(hwloc_bitmap_t bitmap, unsigned begin, int end)
    Add indexes from begin to end in bitmap bitmap.
    -
    hwloc_bitmap_compare_first
    int hwloc_bitmap_compare_first(hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
    Compare bitmaps bitmap1 and bitmap2 using their lowest index.
    -
    hwloc_bitmap_t
    struct hwloc_bitmap_s * hwloc_bitmap_t
    Set of bits represented as an opaque pointer to an internal bitmap.
    Definition: bitmap.h:68
    -
    hwloc_bitmap_singlify
    int hwloc_bitmap_singlify(hwloc_bitmap_t bitmap)
    Keep a single index among those set in bitmap bitmap.
    -
    hwloc_bitmap_zero
    void hwloc_bitmap_zero(hwloc_bitmap_t bitmap)
    Empty the bitmap bitmap.
    -
    hwloc_bitmap_next
    int hwloc_bitmap_next(hwloc_const_bitmap_t bitmap, int prev)
    Compute the next index in bitmap bitmap which is after index prev.
    -
    hwloc_bitmap_to_ulong
    unsigned long hwloc_bitmap_to_ulong(hwloc_const_bitmap_t bitmap)
    Convert the beginning part of bitmap bitmap into unsigned long mask.
    -
    hwloc_bitmap_from_ulongs
    int hwloc_bitmap_from_ulongs(hwloc_bitmap_t bitmap, unsigned nr, const unsigned long *masks)
    Setup bitmap bitmap from unsigned longs masks used as first nr subsets.
    -
    hwloc_bitmap_nr_ulongs
    int hwloc_bitmap_nr_ulongs(hwloc_const_bitmap_t bitmap)
    Return the number of unsigned longs required for storing bitmap bitmap entirely.
    -
    hwloc_bitmap_to_ith_ulong
    unsigned long hwloc_bitmap_to_ith_ulong(hwloc_const_bitmap_t bitmap, unsigned i)
    Convert the i -th subset of bitmap bitmap into unsigned long mask.
    -
    hwloc_bitmap_to_ulongs
    int hwloc_bitmap_to_ulongs(hwloc_const_bitmap_t bitmap, unsigned nr, unsigned long *masks)
    Convert the first nr subsets of bitmap bitmap into the array of nr unsigned long masks.
    -
    hwloc_bitmap_from_ulong
    int hwloc_bitmap_from_ulong(hwloc_bitmap_t bitmap, unsigned long mask)
    Setup bitmap bitmap from unsigned long mask.
    -
    hwloc_bitmap_alloc
    hwloc_bitmap_t hwloc_bitmap_alloc(void)
    Allocate a new empty bitmap.
    -
    hwloc_bitmap_first_unset
    int hwloc_bitmap_first_unset(hwloc_const_bitmap_t bitmap)
    Compute the first unset index (least significant bit) in bitmap bitmap.
    -
    hwloc_bitmap_dup
    hwloc_bitmap_t hwloc_bitmap_dup(hwloc_const_bitmap_t bitmap)
    Duplicate bitmap bitmap by allocating a new bitmap and copying bitmap contents.
    -
    hwloc_const_bitmap_t
    const struct hwloc_bitmap_s * hwloc_const_bitmap_t
    a non-modifiable hwloc_bitmap_t
    Definition: bitmap.h:70
    -
    hwloc_bitmap_intersects
    int hwloc_bitmap_intersects(hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
    Test whether bitmaps bitmap1 and bitmap2 intersects.
    -
    hwloc_bitmap_clr
    int hwloc_bitmap_clr(hwloc_bitmap_t bitmap, unsigned id)
    Remove index id from bitmap bitmap.
    -
    hwloc_bitmap_list_sscanf
    int hwloc_bitmap_list_sscanf(hwloc_bitmap_t bitmap, const char *restrict string)
    Parse a list string and stores it in bitmap bitmap.
    -
    - - - - - - - - -
    -
    -
    export.h
    -
    -
    -
    1 /*
    -
    2  * Copyright © 2009-2018 Inria. All rights reserved.
    -
    3  * Copyright © 2009-2012 Université Bordeaux
    -
    4  * Copyright © 2009-2011 Cisco Systems, Inc. All rights reserved.
    -
    5  * See COPYING in top-level directory.
    -
    6  */
    -
    7 
    -
    12 #ifndef HWLOC_EXPORT_H
    -
    13 #define HWLOC_EXPORT_H
    -
    14 
    -
    15 #ifndef HWLOC_H
    -
    16 #error Please include the main hwloc.h instead
    -
    17 #endif
    -
    18 
    -
    19 
    -
    20 #ifdef __cplusplus
    -
    21 extern "C" {
    -
    22 #elif 0
    -
    23 }
    -
    24 #endif
    -
    25 
    -
    26 
    -
    35 enum hwloc_topology_export_xml_flags_e {
    -
    40  HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1 = (1UL<<0)
    -
    41 };
    -
    42 
    -
    71 HWLOC_DECLSPEC int hwloc_topology_export_xml(hwloc_topology_t topology, const char *xmlpath, unsigned long flags);
    -
    72 
    -
    105 HWLOC_DECLSPEC int hwloc_topology_export_xmlbuffer(hwloc_topology_t topology, char **xmlbuffer, int *buflen, unsigned long flags);
    -
    106 
    -
    108 HWLOC_DECLSPEC void hwloc_free_xmlbuffer(hwloc_topology_t topology, char *xmlbuffer);
    -
    109 
    -
    128 HWLOC_DECLSPEC void hwloc_topology_set_userdata_export_callback(hwloc_topology_t topology,
    -
    129  void (*export_cb)(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj));
    -
    130 
    -
    156 HWLOC_DECLSPEC int hwloc_export_obj_userdata(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length);
    -
    157 
    -
    171 HWLOC_DECLSPEC int hwloc_export_obj_userdata_base64(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length);
    -
    172 
    -
    195 HWLOC_DECLSPEC void hwloc_topology_set_userdata_import_callback(hwloc_topology_t topology,
    -
    196  void (*import_cb)(hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length));
    -
    197 
    -
    209 enum hwloc_topology_export_synthetic_flags_e {
    -
    215  HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_EXTENDED_TYPES = (1UL<<0),
    -
    216 
    -
    223  HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_ATTRS = (1UL<<1),
    -
    224 
    -
    233  HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_V1 = (1UL<<2),
    -
    234 
    -
    243  HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_IGNORE_MEMORY = (1UL<<3)
    -
    244 };
    -
    245 
    -
    267  HWLOC_DECLSPEC int hwloc_topology_export_synthetic(hwloc_topology_t topology, char *buffer, size_t buflen, unsigned long flags);
    -
    268 
    -
    273 #ifdef __cplusplus
    -
    274 } /* extern "C" */
    -
    275 #endif
    -
    276 
    -
    277 
    -
    278 #endif /* HWLOC_EXPORT_H */
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:692
    -
    hwloc_topology_export_xml_flags_e
    hwloc_topology_export_xml_flags_e
    Flags for exporting XML topologies.
    Definition: export.h:35
    -
    hwloc_export_obj_userdata_base64
    int hwloc_export_obj_userdata_base64(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length)
    Encode and export some object userdata to XML.
    -
    hwloc_free_xmlbuffer
    void hwloc_free_xmlbuffer(hwloc_topology_t topology, char *xmlbuffer)
    Free a buffer allocated by hwloc_topology_export_xmlbuffer()
    -
    hwloc_topology_export_xml
    int hwloc_topology_export_xml(hwloc_topology_t topology, const char *xmlpath, unsigned long flags)
    Export the topology into an XML file.
    -
    hwloc_topology_set_userdata_import_callback
    void hwloc_topology_set_userdata_import_callback(hwloc_topology_t topology, void(*import_cb)(hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length))
    Set the application-specific callback for importing userdata.
    -
    hwloc_topology_set_userdata_export_callback
    void hwloc_topology_set_userdata_export_callback(hwloc_topology_t topology, void(*export_cb)(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj))
    Set the application-specific callback for exporting object userdata.
    -
    hwloc_export_obj_userdata
    int hwloc_export_obj_userdata(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length)
    Export some object userdata to XML.
    -
    hwloc_topology_export_xmlbuffer
    int hwloc_topology_export_xmlbuffer(hwloc_topology_t topology, char **xmlbuffer, int *buflen, unsigned long flags)
    Export the topology into a newly-allocated XML memory buffer.
    -
    HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1
    @ HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1
    Export XML that is loadable by hwloc v1.x. However, the export may miss some details about the topolo...
    Definition: export.h:40
    -
    hwloc_topology_export_synthetic
    int hwloc_topology_export_synthetic(hwloc_topology_t topology, char *buffer, size_t buflen, unsigned long flags)
    Export the topology as a synthetic string.
    -
    hwloc_topology_export_synthetic_flags_e
    hwloc_topology_export_synthetic_flags_e
    Flags for exporting synthetic topologies.
    Definition: export.h:209
    -
    HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_IGNORE_MEMORY
    @ HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_IGNORE_MEMORY
    Do not export memory information.
    Definition: export.h:243
    -
    HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_EXTENDED_TYPES
    @ HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_EXTENDED_TYPES
    Export extended types such as L2dcache as basic types such as Cache.
    Definition: export.h:215
    -
    HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_V1
    @ HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_V1
    Export the memory hierarchy as expected in hwloc 1.x.
    Definition: export.h:233
    -
    HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_ATTRS
    @ HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_ATTRS
    Do not export level attributes.
    Definition: export.h:223
    -
    hwloc_obj
    Structure of a topology object.
    Definition: hwloc.h:396
    -
    - - - - - - - - -
    -
    -
    distances.h
    -
    -
    -
    1 /*
    -
    2  * Copyright © 2010-2022 Inria. All rights reserved.
    -
    3  * See COPYING in top-level directory.
    -
    4  */
    -
    5 
    -
    10 #ifndef HWLOC_DISTANCES_H
    -
    11 #define HWLOC_DISTANCES_H
    -
    12 
    -
    13 #ifndef HWLOC_H
    -
    14 #error Please include the main hwloc.h instead
    -
    15 #endif
    -
    16 
    -
    17 
    -
    18 #ifdef __cplusplus
    -
    19 extern "C" {
    -
    20 #elif 0
    -
    21 }
    -
    22 #endif
    -
    23 
    -
    24 
    -
    53 struct hwloc_distances_s {
    -
    54  unsigned nbobjs;
    -
    55  hwloc_obj_t *objs;
    -
    60  unsigned long kind;
    -
    61  hwloc_uint64_t *values;
    -
    66 };
    -
    67 
    -
    79 enum hwloc_distances_kind_e {
    -
    83  HWLOC_DISTANCES_KIND_FROM_OS = (1UL<<0),
    -
    87  HWLOC_DISTANCES_KIND_FROM_USER = (1UL<<1),
    -
    88 
    -
    95  HWLOC_DISTANCES_KIND_MEANS_LATENCY = (1UL<<2),
    -
    102  HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH = (1UL<<3),
    -
    103 
    -
    109  HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES = (1UL<<4)
    -
    110 };
    -
    111 
    -
    135 HWLOC_DECLSPEC int
    -
    136 hwloc_distances_get(hwloc_topology_t topology,
    -
    137  unsigned *nr, struct hwloc_distances_s **distances,
    -
    138  unsigned long kind, unsigned long flags);
    -
    139 
    -
    144 HWLOC_DECLSPEC int
    -
    145 hwloc_distances_get_by_depth(hwloc_topology_t topology, int depth,
    -
    146  unsigned *nr, struct hwloc_distances_s **distances,
    -
    147  unsigned long kind, unsigned long flags);
    -
    148 
    -
    153 HWLOC_DECLSPEC int
    -
    154 hwloc_distances_get_by_type(hwloc_topology_t topology, hwloc_obj_type_t type,
    -
    155  unsigned *nr, struct hwloc_distances_s **distances,
    -
    156  unsigned long kind, unsigned long flags);
    -
    157 
    -
    166 HWLOC_DECLSPEC int
    -
    167 hwloc_distances_get_by_name(hwloc_topology_t topology, const char *name,
    -
    168  unsigned *nr, struct hwloc_distances_s **distances,
    -
    169  unsigned long flags);
    -
    170 
    -
    176 HWLOC_DECLSPEC const char *
    -
    177 hwloc_distances_get_name(hwloc_topology_t topology, struct hwloc_distances_s *distances);
    -
    178 
    -
    183 HWLOC_DECLSPEC void
    -
    184 hwloc_distances_release(hwloc_topology_t topology, struct hwloc_distances_s *distances);
    -
    185 
    -
    187 enum hwloc_distances_transform_e {
    -
    201  HWLOC_DISTANCES_TRANSFORM_REMOVE_NULL = 0,
    -
    202 
    -
    215  HWLOC_DISTANCES_TRANSFORM_LINKS = 1,
    -
    216 
    -
    224  HWLOC_DISTANCES_TRANSFORM_MERGE_SWITCH_PORTS = 2,
    -
    225 
    -
    231  HWLOC_DISTANCES_TRANSFORM_TRANSITIVE_CLOSURE = 3
    -
    232 };
    -
    233 
    -
    260 HWLOC_DECLSPEC int hwloc_distances_transform(hwloc_topology_t topology, struct hwloc_distances_s *distances,
    -
    261  enum hwloc_distances_transform_e transform,
    -
    262  void *transform_attr,
    -
    263  unsigned long flags);
    -
    264 
    -
    277 static __hwloc_inline int
    -
    278 hwloc_distances_obj_index(struct hwloc_distances_s *distances, hwloc_obj_t obj)
    -
    279 {
    -
    280  unsigned i;
    -
    281  for(i=0; i<distances->nbobjs; i++)
    -
    282  if (distances->objs[i] == obj)
    -
    283  return (int)i;
    -
    284  return -1;
    -
    285 }
    -
    286 
    -
    294 static __hwloc_inline int
    -
    295 hwloc_distances_obj_pair_values(struct hwloc_distances_s *distances,
    -
    296  hwloc_obj_t obj1, hwloc_obj_t obj2,
    -
    297  hwloc_uint64_t *value1to2, hwloc_uint64_t *value2to1)
    -
    298 {
    -
    299  int i1 = hwloc_distances_obj_index(distances, obj1);
    -
    300  int i2 = hwloc_distances_obj_index(distances, obj2);
    -
    301  if (i1 < 0 || i2 < 0)
    -
    302  return -1;
    -
    303  *value1to2 = distances->values[i1 * distances->nbobjs + i2];
    -
    304  *value2to1 = distances->values[i2 * distances->nbobjs + i1];
    -
    305  return 0;
    -
    306 }
    -
    307 
    -
    331 typedef void * hwloc_distances_add_handle_t;
    -
    332 
    -
    353 HWLOC_DECLSPEC hwloc_distances_add_handle_t
    -
    354 hwloc_distances_add_create(hwloc_topology_t topology,
    -
    355  const char *name, unsigned long kind,
    -
    356  unsigned long flags);
    -
    357 
    -
    380 HWLOC_DECLSPEC int hwloc_distances_add_values(hwloc_topology_t topology,
    -
    381  hwloc_distances_add_handle_t handle,
    -
    382  unsigned nbobjs, hwloc_obj_t *objs,
    -
    383  hwloc_uint64_t *values,
    -
    384  unsigned long flags);
    -
    385 
    -
    387 enum hwloc_distances_add_flag_e {
    -
    392  HWLOC_DISTANCES_ADD_FLAG_GROUP = (1UL<<0),
    -
    398  HWLOC_DISTANCES_ADD_FLAG_GROUP_INACCURATE = (1UL<<1)
    -
    399 };
    -
    400 
    -
    417 HWLOC_DECLSPEC int hwloc_distances_add_commit(hwloc_topology_t topology,
    -
    418  hwloc_distances_add_handle_t handle,
    -
    419  unsigned long flags);
    -
    420 
    -
    437 HWLOC_DECLSPEC int hwloc_distances_remove(hwloc_topology_t topology);
    -
    438 
    -
    443 HWLOC_DECLSPEC int hwloc_distances_remove_by_depth(hwloc_topology_t topology, int depth);
    -
    444 
    -
    449 static __hwloc_inline int
    -
    450 hwloc_distances_remove_by_type(hwloc_topology_t topology, hwloc_obj_type_t type)
    -
    451 {
    -
    452  int depth = hwloc_get_type_depth(topology, type);
    -
    453  if (depth == HWLOC_TYPE_DEPTH_UNKNOWN || depth == HWLOC_TYPE_DEPTH_MULTIPLE)
    -
    454  return 0;
    -
    455  return hwloc_distances_remove_by_depth(topology, depth);
    -
    456 }
    -
    457 
    -
    462 HWLOC_DECLSPEC int hwloc_distances_release_remove(hwloc_topology_t topology, struct hwloc_distances_s *distances);
    -
    463 
    -
    467 #ifdef __cplusplus
    -
    468 } /* extern "C" */
    -
    469 #endif
    -
    470 
    -
    471 
    -
    472 #endif /* HWLOC_DISTANCES_H */
    -
    hwloc_obj_type_t
    hwloc_obj_type_t
    Type of topology object.
    Definition: hwloc.h:176
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:692
    -
    hwloc_get_type_depth
    int hwloc_get_type_depth(hwloc_topology_t topology, hwloc_obj_type_t type)
    Returns the depth of objects of type type.
    -
    HWLOC_TYPE_DEPTH_UNKNOWN
    @ HWLOC_TYPE_DEPTH_UNKNOWN
    No object of given type exists in the topology.
    Definition: hwloc.h:822
    -
    HWLOC_TYPE_DEPTH_MULTIPLE
    @ HWLOC_TYPE_DEPTH_MULTIPLE
    Objects of given type exist at different depth in the topology (only for Groups).
    Definition: hwloc.h:823
    -
    hwloc_distances_release
    void hwloc_distances_release(hwloc_topology_t topology, struct hwloc_distances_s *distances)
    Release a distance matrix structure previously returned by hwloc_distances_get().
    -
    hwloc_distances_transform_e
    hwloc_distances_transform_e
    Transformations of distances structures.
    Definition: distances.h:187
    -
    hwloc_distances_get_by_depth
    int hwloc_distances_get_by_depth(hwloc_topology_t topology, int depth, unsigned *nr, struct hwloc_distances_s **distances, unsigned long kind, unsigned long flags)
    Retrieve distance matrices for object at a specific depth in the topology.
    -
    hwloc_distances_get
    int hwloc_distances_get(hwloc_topology_t topology, unsigned *nr, struct hwloc_distances_s **distances, unsigned long kind, unsigned long flags)
    Retrieve distance matrices.
    -
    hwloc_distances_get_by_name
    int hwloc_distances_get_by_name(hwloc_topology_t topology, const char *name, unsigned *nr, struct hwloc_distances_s **distances, unsigned long flags)
    Retrieve a distance matrix with the given name.
    -
    hwloc_distances_get_name
    const char * hwloc_distances_get_name(hwloc_topology_t topology, struct hwloc_distances_s *distances)
    Get a description of what a distances structure contains.
    -
    hwloc_distances_get_by_type
    int hwloc_distances_get_by_type(hwloc_topology_t topology, hwloc_obj_type_t type, unsigned *nr, struct hwloc_distances_s **distances, unsigned long kind, unsigned long flags)
    Retrieve distance matrices for object of a specific type.
    -
    hwloc_distances_kind_e
    hwloc_distances_kind_e
    Kinds of distance matrices.
    Definition: distances.h:79
    -
    hwloc_distances_transform
    int hwloc_distances_transform(hwloc_topology_t topology, struct hwloc_distances_s *distances, enum hwloc_distances_transform_e transform, void *transform_attr, unsigned long flags)
    Apply a transformation to a distances structure.
    -
    HWLOC_DISTANCES_TRANSFORM_TRANSITIVE_CLOSURE
    @ HWLOC_DISTANCES_TRANSFORM_TRANSITIVE_CLOSURE
    Apply a transitive closure to the matrix to connect objects across switches. This currently only appl...
    Definition: distances.h:231
    -
    HWLOC_DISTANCES_TRANSFORM_MERGE_SWITCH_PORTS
    @ HWLOC_DISTANCES_TRANSFORM_MERGE_SWITCH_PORTS
    Merge switches with multiple ports into a single object. This currently only applies to NVSwitches wh...
    Definition: distances.h:224
    -
    HWLOC_DISTANCES_TRANSFORM_LINKS
    @ HWLOC_DISTANCES_TRANSFORM_LINKS
    Replace bandwidth values with a number of links.
    Definition: distances.h:215
    -
    HWLOC_DISTANCES_TRANSFORM_REMOVE_NULL
    @ HWLOC_DISTANCES_TRANSFORM_REMOVE_NULL
    Remove NULL objects from the distances structure.
    Definition: distances.h:201
    -
    HWLOC_DISTANCES_KIND_FROM_USER
    @ HWLOC_DISTANCES_KIND_FROM_USER
    These distances were provided by the user.
    Definition: distances.h:87
    -
    HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH
    @ HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH
    Distance values are similar to bandwidths between objects. Values are higher for closer objects,...
    Definition: distances.h:102
    -
    HWLOC_DISTANCES_KIND_FROM_OS
    @ HWLOC_DISTANCES_KIND_FROM_OS
    These distances were obtained from the operating system or hardware.
    Definition: distances.h:83
    -
    HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES
    @ HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES
    This distances structure covers objects of different types. This may apply to the "NVLinkBandwidth" s...
    Definition: distances.h:109
    -
    HWLOC_DISTANCES_KIND_MEANS_LATENCY
    @ HWLOC_DISTANCES_KIND_MEANS_LATENCY
    Distance values are similar to latencies between objects. Values are smaller for closer objects,...
    Definition: distances.h:95
    -
    hwloc_distances_obj_pair_values
    static int hwloc_distances_obj_pair_values(struct hwloc_distances_s *distances, hwloc_obj_t obj1, hwloc_obj_t obj2, hwloc_uint64_t *value1to2, hwloc_uint64_t *value2to1)
    Find the values between two objects in a distance matrices.
    Definition: distances.h:295
    -
    hwloc_distances_obj_index
    static int hwloc_distances_obj_index(struct hwloc_distances_s *distances, hwloc_obj_t obj)
    Find the index of an object in a distances structure.
    Definition: distances.h:278
    -
    hwloc_distances_add_commit
    int hwloc_distances_add_commit(hwloc_topology_t topology, hwloc_distances_add_handle_t handle, unsigned long flags)
    Commit a new distances structure.
    -
    hwloc_distances_add_flag_e
    hwloc_distances_add_flag_e
    Flags for adding a new distances to a topology.
    Definition: distances.h:387
    -
    hwloc_distances_add_handle_t
    void * hwloc_distances_add_handle_t
    Handle to a new distances structure during its addition to the topology.
    Definition: distances.h:331
    -
    hwloc_distances_add_create
    hwloc_distances_add_handle_t hwloc_distances_add_create(hwloc_topology_t topology, const char *name, unsigned long kind, unsigned long flags)
    Create a new empty distances structure.
    -
    hwloc_distances_add_values
    int hwloc_distances_add_values(hwloc_topology_t topology, hwloc_distances_add_handle_t handle, unsigned nbobjs, hwloc_obj_t *objs, hwloc_uint64_t *values, unsigned long flags)
    Specify the objects and values in a new empty distances structure.
    -
    HWLOC_DISTANCES_ADD_FLAG_GROUP_INACCURATE
    @ HWLOC_DISTANCES_ADD_FLAG_GROUP_INACCURATE
    If grouping, consider the distance values as inaccurate and relax the comparisons during the grouping...
    Definition: distances.h:398
    -
    HWLOC_DISTANCES_ADD_FLAG_GROUP
    @ HWLOC_DISTANCES_ADD_FLAG_GROUP
    Try to group objects based on the newly provided distance information. This is ignored for distances ...
    Definition: distances.h:392
    -
    hwloc_distances_release_remove
    int hwloc_distances_release_remove(hwloc_topology_t topology, struct hwloc_distances_s *distances)
    Release and remove the given distance matrice from the topology.
    -
    hwloc_distances_remove_by_type
    static int hwloc_distances_remove_by_type(hwloc_topology_t topology, hwloc_obj_type_t type)
    Remove distance matrices for objects of a specific type in the topology.
    Definition: distances.h:450
    -
    hwloc_distances_remove_by_depth
    int hwloc_distances_remove_by_depth(hwloc_topology_t topology, int depth)
    Remove distance matrices for objects at a specific depth in the topology.
    -
    hwloc_distances_remove
    int hwloc_distances_remove(hwloc_topology_t topology)
    Remove all distance matrices from a topology.
    -
    hwloc_obj
    Structure of a topology object.
    Definition: hwloc.h:396
    -
    hwloc_distances_s
    Matrix of distances between a set of objects.
    Definition: distances.h:53
    -
    hwloc_distances_s::nbobjs
    unsigned nbobjs
    Number of objects described by the distance matrix.
    Definition: distances.h:54
    -
    hwloc_distances_s::values
    hwloc_uint64_t * values
    Matrix of distances between objects, stored as a one-dimension array.
    Definition: distances.h:61
    -
    hwloc_distances_s::kind
    unsigned long kind
    OR'ed set of hwloc_distances_kind_e.
    Definition: distances.h:60
    -
    hwloc_distances_s::objs
    hwloc_obj_t * objs
    Array of objects described by the distance matrix. These objects are not in any particular order,...
    Definition: distances.h:55
    -
    - - - - - - - - -
    -
    -
    memattrs.h
    -
    -
    -
    1 /*
    -
    2  * Copyright © 2019-2022 Inria. All rights reserved.
    -
    3  * See COPYING in top-level directory.
    -
    4  */
    -
    5 
    -
    10 #ifndef HWLOC_MEMATTR_H
    -
    11 #define HWLOC_MEMATTR_H
    -
    12 
    -
    13 #include "hwloc.h"
    -
    14 
    -
    15 #ifdef __cplusplus
    -
    16 extern "C" {
    -
    17 #elif 0
    -
    18 }
    -
    19 #endif
    -
    20 
    -
    69 enum hwloc_memattr_id_e {
    -
    79  HWLOC_MEMATTR_ID_CAPACITY = 0,
    -
    80 
    -
    94  HWLOC_MEMATTR_ID_LOCALITY = 1,
    -
    95 
    -
    109  HWLOC_MEMATTR_ID_BANDWIDTH = 2,
    -
    110 
    -
    120  HWLOC_MEMATTR_ID_READ_BANDWIDTH = 4,
    -
    121 
    -
    131  HWLOC_MEMATTR_ID_WRITE_BANDWIDTH = 5,
    -
    132 
    -
    146  HWLOC_MEMATTR_ID_LATENCY = 3,
    -
    147 
    -
    157  HWLOC_MEMATTR_ID_READ_LATENCY = 6,
    -
    158 
    -
    168  HWLOC_MEMATTR_ID_WRITE_LATENCY = 7,
    -
    169 
    -
    170  /* TODO persistence? */
    -
    171 
    -
    172  HWLOC_MEMATTR_ID_MAX
    -
    173 };
    -
    174 
    -
    178 typedef unsigned hwloc_memattr_id_t;
    -
    179 
    -
    182 HWLOC_DECLSPEC int
    -
    183 hwloc_memattr_get_by_name(hwloc_topology_t topology,
    -
    184  const char *name,
    -
    185  hwloc_memattr_id_t *id);
    -
    186 
    -
    187 
    -
    189 enum hwloc_location_type_e {
    -
    191  HWLOC_LOCATION_TYPE_CPUSET = 1,
    -
    193  HWLOC_LOCATION_TYPE_OBJECT = 0
    -
    194 };
    -
    195 
    -
    197 struct hwloc_location {
    -
    199  enum hwloc_location_type_e type;
    -
    201  union hwloc_location_u {
    -
    203  hwloc_cpuset_t cpuset;
    -
    205  hwloc_obj_t object;
    -
    206  } location;
    -
    207 };
    -
    208 
    -
    209 
    -
    211 enum hwloc_local_numanode_flag_e {
    -
    217  HWLOC_LOCAL_NUMANODE_FLAG_LARGER_LOCALITY = (1UL<<0),
    -
    218 
    -
    224  HWLOC_LOCAL_NUMANODE_FLAG_SMALLER_LOCALITY = (1UL<<1),
    -
    225 
    -
    230  HWLOC_LOCAL_NUMANODE_FLAG_ALL = (1UL<<2)
    -
    231 };
    -
    232 
    -
    262 HWLOC_DECLSPEC int
    -
    263 hwloc_get_local_numanode_objs(hwloc_topology_t topology,
    -
    264  struct hwloc_location *location,
    -
    265  unsigned *nr,
    -
    266  hwloc_obj_t *nodes,
    -
    267  unsigned long flags);
    -
    268 
    -
    269 
    -
    270 
    -
    285 HWLOC_DECLSPEC int
    -
    286 hwloc_memattr_get_value(hwloc_topology_t topology,
    -
    287  hwloc_memattr_id_t attribute,
    -
    288  hwloc_obj_t target_node,
    -
    289  struct hwloc_location *initiator,
    -
    290  unsigned long flags,
    -
    291  hwloc_uint64_t *value);
    -
    292 
    -
    318 HWLOC_DECLSPEC int
    -
    319 hwloc_memattr_get_best_target(hwloc_topology_t topology,
    -
    320  hwloc_memattr_id_t attribute,
    -
    321  struct hwloc_location *initiator,
    -
    322  unsigned long flags,
    -
    323  hwloc_obj_t *best_target, hwloc_uint64_t *value);
    -
    324 
    -
    347 HWLOC_DECLSPEC int
    -
    348 hwloc_memattr_get_best_initiator(hwloc_topology_t topology,
    -
    349  hwloc_memattr_id_t attribute,
    -
    350  hwloc_obj_t target,
    -
    351  unsigned long flags,
    -
    352  struct hwloc_location *best_initiator, hwloc_uint64_t *value);
    -
    353 
    -
    363 HWLOC_DECLSPEC int
    -
    364 hwloc_memattr_get_name(hwloc_topology_t topology,
    -
    365  hwloc_memattr_id_t attribute,
    -
    366  const char **name);
    -
    367 
    -
    372 HWLOC_DECLSPEC int
    -
    373 hwloc_memattr_get_flags(hwloc_topology_t topology,
    -
    374  hwloc_memattr_id_t attribute,
    -
    375  unsigned long *flags);
    -
    376 
    -
    380 enum hwloc_memattr_flag_e {
    -
    384  HWLOC_MEMATTR_FLAG_HIGHER_FIRST = (1UL<<0),
    -
    388  HWLOC_MEMATTR_FLAG_LOWER_FIRST = (1UL<<1),
    -
    392  HWLOC_MEMATTR_FLAG_NEED_INITIATOR = (1UL<<2)
    -
    393 };
    -
    394 
    -
    401 HWLOC_DECLSPEC int
    -
    402 hwloc_memattr_register(hwloc_topology_t topology,
    -
    403  const char *name,
    -
    404  unsigned long flags,
    -
    405  hwloc_memattr_id_t *id);
    -
    406 
    -
    425 HWLOC_DECLSPEC int
    -
    426 hwloc_memattr_set_value(hwloc_topology_t topology,
    -
    427  hwloc_memattr_id_t attribute,
    -
    428  hwloc_obj_t target_node,
    -
    429  struct hwloc_location *initiator,
    -
    430  unsigned long flags,
    -
    431  hwloc_uint64_t value);
    -
    432 
    -
    469 HWLOC_DECLSPEC int
    -
    470 hwloc_memattr_get_targets(hwloc_topology_t topology,
    -
    471  hwloc_memattr_id_t attribute,
    -
    472  struct hwloc_location *initiator,
    -
    473  unsigned long flags,
    -
    474  unsigned *nr, hwloc_obj_t *targets, hwloc_uint64_t *values);
    -
    475 
    -
    505 HWLOC_DECLSPEC int
    -
    506 hwloc_memattr_get_initiators(hwloc_topology_t topology,
    -
    507  hwloc_memattr_id_t attribute,
    -
    508  hwloc_obj_t target_node,
    -
    509  unsigned long flags,
    -
    510  unsigned *nr, struct hwloc_location *initiators, hwloc_uint64_t *values);
    -
    513 #ifdef __cplusplus
    -
    514 } /* extern "C" */
    -
    515 #endif
    -
    516 
    -
    517 
    -
    518 #endif /* HWLOC_MEMATTR_H */
    -
    hwloc_cpuset_t
    hwloc_bitmap_t hwloc_cpuset_t
    A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
    Definition: hwloc.h:140
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:692
    -
    hwloc_memattr_get_value
    int hwloc_memattr_get_value(hwloc_topology_t topology, hwloc_memattr_id_t attribute, hwloc_obj_t target_node, struct hwloc_location *initiator, unsigned long flags, hwloc_uint64_t *value)
    Return an attribute value for a specific target NUMA node.
    -
    hwloc_location_type_e
    hwloc_location_type_e
    Type of location.
    Definition: memattrs.h:189
    -
    hwloc_get_local_numanode_objs
    int hwloc_get_local_numanode_objs(hwloc_topology_t topology, struct hwloc_location *location, unsigned *nr, hwloc_obj_t *nodes, unsigned long flags)
    Return an array of local NUMA nodes.
    -
    hwloc_memattr_get_by_name
    int hwloc_memattr_get_by_name(hwloc_topology_t topology, const char *name, hwloc_memattr_id_t *id)
    Return the identifier of the memory attribute with the given name.
    -
    hwloc_memattr_get_best_target
    int hwloc_memattr_get_best_target(hwloc_topology_t topology, hwloc_memattr_id_t attribute, struct hwloc_location *initiator, unsigned long flags, hwloc_obj_t *best_target, hwloc_uint64_t *value)
    Return the best target NUMA node for the given attribute and initiator.
    -
    hwloc_memattr_get_best_initiator
    int hwloc_memattr_get_best_initiator(hwloc_topology_t topology, hwloc_memattr_id_t attribute, hwloc_obj_t target, unsigned long flags, struct hwloc_location *best_initiator, hwloc_uint64_t *value)
    Return the best initiator for the given attribute and target NUMA node.
    -
    hwloc_memattr_id_e
    hwloc_memattr_id_e
    Memory node attributes.
    Definition: memattrs.h:69
    -
    hwloc_local_numanode_flag_e
    hwloc_local_numanode_flag_e
    Flags for selecting target NUMA nodes.
    Definition: memattrs.h:211
    -
    hwloc_memattr_id_t
    unsigned hwloc_memattr_id_t
    A memory attribute identifier. May be either one of hwloc_memattr_id_e or a new id returned by hwloc_...
    Definition: memattrs.h:178
    -
    HWLOC_LOCATION_TYPE_CPUSET
    @ HWLOC_LOCATION_TYPE_CPUSET
    Location is given as a cpuset, in the location cpuset union field.
    Definition: memattrs.h:191
    -
    HWLOC_LOCATION_TYPE_OBJECT
    @ HWLOC_LOCATION_TYPE_OBJECT
    Location is given as an object, in the location object union field.
    Definition: memattrs.h:193
    -
    HWLOC_MEMATTR_ID_BANDWIDTH
    @ HWLOC_MEMATTR_ID_BANDWIDTH
    The "Bandwidth" is returned in MiB/s, as seen from the given initiator location.
    Definition: memattrs.h:109
    -
    HWLOC_MEMATTR_ID_WRITE_BANDWIDTH
    @ HWLOC_MEMATTR_ID_WRITE_BANDWIDTH
    The "WriteBandwidth" is returned in MiB/s, as seen from the given initiator location.
    Definition: memattrs.h:131
    -
    HWLOC_MEMATTR_ID_READ_LATENCY
    @ HWLOC_MEMATTR_ID_READ_LATENCY
    The "ReadLatency" is returned as nanoseconds, as seen from the given initiator location.
    Definition: memattrs.h:157
    -
    HWLOC_MEMATTR_ID_LOCALITY
    @ HWLOC_MEMATTR_ID_LOCALITY
    The "Locality" is returned as the number of PUs in that locality (e.g. the weight of its cpuset).
    Definition: memattrs.h:94
    -
    HWLOC_MEMATTR_ID_CAPACITY
    @ HWLOC_MEMATTR_ID_CAPACITY
    The "Capacity" is returned in bytes (local_memory attribute in objects).
    Definition: memattrs.h:79
    -
    HWLOC_MEMATTR_ID_WRITE_LATENCY
    @ HWLOC_MEMATTR_ID_WRITE_LATENCY
    The "WriteLatency" is returned as nanoseconds, as seen from the given initiator location.
    Definition: memattrs.h:168
    -
    HWLOC_MEMATTR_ID_READ_BANDWIDTH
    @ HWLOC_MEMATTR_ID_READ_BANDWIDTH
    The "ReadBandwidth" is returned in MiB/s, as seen from the given initiator location.
    Definition: memattrs.h:120
    -
    HWLOC_MEMATTR_ID_LATENCY
    @ HWLOC_MEMATTR_ID_LATENCY
    The "Latency" is returned as nanoseconds, as seen from the given initiator location.
    Definition: memattrs.h:146
    -
    HWLOC_LOCAL_NUMANODE_FLAG_LARGER_LOCALITY
    @ HWLOC_LOCAL_NUMANODE_FLAG_LARGER_LOCALITY
    Select NUMA nodes whose locality is larger than the given cpuset. For instance, if a single PU (or it...
    Definition: memattrs.h:217
    -
    HWLOC_LOCAL_NUMANODE_FLAG_SMALLER_LOCALITY
    @ HWLOC_LOCAL_NUMANODE_FLAG_SMALLER_LOCALITY
    Select NUMA nodes whose locality is smaller than the given cpuset. For instance, if a package (or its...
    Definition: memattrs.h:224
    -
    HWLOC_LOCAL_NUMANODE_FLAG_ALL
    @ HWLOC_LOCAL_NUMANODE_FLAG_ALL
    Select all NUMA nodes in the topology. The initiator initiator is ignored.
    Definition: memattrs.h:230
    -
    hwloc_memattr_get_initiators
    int hwloc_memattr_get_initiators(hwloc_topology_t topology, hwloc_memattr_id_t attribute, hwloc_obj_t target_node, unsigned long flags, unsigned *nr, struct hwloc_location *initiators, hwloc_uint64_t *values)
    Return the initiators that have values for a given attribute for a specific target NUMA node.
    -
    hwloc_memattr_get_flags
    int hwloc_memattr_get_flags(hwloc_topology_t topology, hwloc_memattr_id_t attribute, unsigned long *flags)
    Return the flags of the given attribute.
    -
    hwloc_memattr_get_name
    int hwloc_memattr_get_name(hwloc_topology_t topology, hwloc_memattr_id_t attribute, const char **name)
    Return the name of a memory attribute.
    -
    hwloc_memattr_register
    int hwloc_memattr_register(hwloc_topology_t topology, const char *name, unsigned long flags, hwloc_memattr_id_t *id)
    Register a new memory attribute.
    -
    hwloc_memattr_flag_e
    hwloc_memattr_flag_e
    Memory attribute flags. Given to hwloc_memattr_register() and returned by hwloc_memattr_get_flags().
    Definition: memattrs.h:380
    -
    hwloc_memattr_set_value
    int hwloc_memattr_set_value(hwloc_topology_t topology, hwloc_memattr_id_t attribute, hwloc_obj_t target_node, struct hwloc_location *initiator, unsigned long flags, hwloc_uint64_t value)
    Set an attribute value for a specific target NUMA node.
    -
    hwloc_memattr_get_targets
    int hwloc_memattr_get_targets(hwloc_topology_t topology, hwloc_memattr_id_t attribute, struct hwloc_location *initiator, unsigned long flags, unsigned *nr, hwloc_obj_t *targets, hwloc_uint64_t *values)
    Return the target NUMA nodes that have some values for a given attribute.
    -
    HWLOC_MEMATTR_FLAG_LOWER_FIRST
    @ HWLOC_MEMATTR_FLAG_LOWER_FIRST
    The best nodes for this memory attribute are those with the lower values. For instance Latency.
    Definition: memattrs.h:388
    -
    HWLOC_MEMATTR_FLAG_NEED_INITIATOR
    @ HWLOC_MEMATTR_FLAG_NEED_INITIATOR
    The value returned for this memory attribute depends on the given initiator. For instance Bandwidth a...
    Definition: memattrs.h:392
    -
    HWLOC_MEMATTR_FLAG_HIGHER_FIRST
    @ HWLOC_MEMATTR_FLAG_HIGHER_FIRST
    The best nodes for this memory attribute are those with the higher values. For instance Bandwidth.
    Definition: memattrs.h:384
    -
    hwloc_obj
    Structure of a topology object.
    Definition: hwloc.h:396
    -
    hwloc_location
    Where to measure attributes from.
    Definition: memattrs.h:197
    -
    hwloc_location::location
    union hwloc_location::hwloc_location_u location
    -
    hwloc_location::type
    enum hwloc_location_type_e type
    Type of location.
    Definition: memattrs.h:199
    -
    hwloc_location::hwloc_location_u
    Actual location.
    Definition: memattrs.h:201
    -
    hwloc_location::hwloc_location_u::cpuset
    hwloc_cpuset_t cpuset
    Location as a cpuset, when the location type is HWLOC_LOCATION_TYPE_CPUSET.
    Definition: memattrs.h:203
    -
    hwloc_location::hwloc_location_u::object
    hwloc_obj_t object
    Location as an object, when the location type is HWLOC_LOCATION_TYPE_OBJECT.
    Definition: memattrs.h:205
    -
    - - - - - - - - -
    -
    -
    cpukinds.h
    -
    -
    -
    1 /*
    -
    2  * Copyright © 2020-2021 Inria. All rights reserved.
    -
    3  * See COPYING in top-level directory.
    -
    4  */
    -
    5 
    -
    10 #ifndef HWLOC_CPUKINDS_H
    -
    11 #define HWLOC_CPUKINDS_H
    -
    12 
    -
    13 #include "hwloc.h"
    -
    14 
    -
    15 #ifdef __cplusplus
    -
    16 extern "C" {
    -
    17 #elif 0
    -
    18 }
    -
    19 #endif
    -
    20 
    -
    81 HWLOC_DECLSPEC int
    -
    82 hwloc_cpukinds_get_nr(hwloc_topology_t topology,
    -
    83  unsigned long flags);
    -
    84 
    -
    96 HWLOC_DECLSPEC int
    -
    97 hwloc_cpukinds_get_by_cpuset(hwloc_topology_t topology,
    -
    98  hwloc_const_bitmap_t cpuset,
    -
    99  unsigned long flags);
    -
    100 
    -
    134 HWLOC_DECLSPEC int
    -
    135 hwloc_cpukinds_get_info(hwloc_topology_t topology,
    -
    136  unsigned kind_index,
    -
    137  hwloc_bitmap_t cpuset,
    -
    138  int *efficiency,
    -
    139  unsigned *nr_infos, struct hwloc_info_s **infos,
    -
    140  unsigned long flags);
    -
    141 
    -
    179 HWLOC_DECLSPEC int
    -
    180 hwloc_cpukinds_register(hwloc_topology_t topology,
    -
    181  hwloc_bitmap_t cpuset,
    -
    182  int forced_efficiency,
    -
    183  unsigned nr_infos, struct hwloc_info_s *infos,
    -
    184  unsigned long flags);
    -
    185 
    -
    188 #ifdef __cplusplus
    -
    189 } /* extern "C" */
    -
    190 #endif
    -
    191 
    -
    192 
    -
    193 #endif /* HWLOC_CPUKINDS_H */
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:692
    -
    hwloc_bitmap_t
    struct hwloc_bitmap_s * hwloc_bitmap_t
    Set of bits represented as an opaque pointer to an internal bitmap.
    Definition: bitmap.h:68
    -
    hwloc_const_bitmap_t
    const struct hwloc_bitmap_s * hwloc_const_bitmap_t
    a non-modifiable hwloc_bitmap_t
    Definition: bitmap.h:70
    -
    hwloc_cpukinds_register
    int hwloc_cpukinds_register(hwloc_topology_t topology, hwloc_bitmap_t cpuset, int forced_efficiency, unsigned nr_infos, struct hwloc_info_s *infos, unsigned long flags)
    Register a kind of CPU in the topology.
    -
    hwloc_cpukinds_get_nr
    int hwloc_cpukinds_get_nr(hwloc_topology_t topology, unsigned long flags)
    Get the number of different kinds of CPU cores in the topology.
    -
    hwloc_cpukinds_get_info
    int hwloc_cpukinds_get_info(hwloc_topology_t topology, unsigned kind_index, hwloc_bitmap_t cpuset, int *efficiency, unsigned *nr_infos, struct hwloc_info_s **infos, unsigned long flags)
    Get the CPU set and infos about a CPU kind in the topology.
    -
    hwloc_cpukinds_get_by_cpuset
    int hwloc_cpukinds_get_by_cpuset(hwloc_topology_t topology, hwloc_const_bitmap_t cpuset, unsigned long flags)
    Get the index of the CPU kind that contains CPUs listed in cpuset.
    -
    hwloc_info_s
    Object info.
    Definition: hwloc.h:674
    -
    - - - - - - - - -
    -
    -
    linux.h
    -
    -
    -
    1 /*
    -
    2  * Copyright © 2009 CNRS
    -
    3  * Copyright © 2009-2021 Inria. All rights reserved.
    -
    4  * Copyright © 2009-2011 Université Bordeaux
    -
    5  * See COPYING in top-level directory.
    -
    6  */
    -
    7 
    -
    15 #ifndef HWLOC_LINUX_H
    -
    16 #define HWLOC_LINUX_H
    -
    17 
    -
    18 #include "hwloc.h"
    -
    19 
    -
    20 #include <stdio.h>
    -
    21 
    -
    22 
    -
    23 #ifdef __cplusplus
    -
    24 extern "C" {
    -
    25 #endif
    -
    26 
    -
    27 
    -
    44 HWLOC_DECLSPEC int hwloc_linux_set_tid_cpubind(hwloc_topology_t topology, pid_t tid, hwloc_const_cpuset_t set);
    -
    45 
    -
    58 HWLOC_DECLSPEC int hwloc_linux_get_tid_cpubind(hwloc_topology_t topology, pid_t tid, hwloc_cpuset_t set);
    -
    59 
    -
    68 HWLOC_DECLSPEC int hwloc_linux_get_tid_last_cpu_location(hwloc_topology_t topology, pid_t tid, hwloc_bitmap_t set);
    -
    69 
    -
    77 HWLOC_DECLSPEC int hwloc_linux_read_path_as_cpumask(const char *path, hwloc_bitmap_t set);
    -
    78 
    -
    82 #ifdef __cplusplus
    -
    83 } /* extern "C" */
    -
    84 #endif
    -
    85 
    -
    86 
    -
    87 #endif /* HWLOC_LINUX_H */
    -
    hwloc_const_cpuset_t
    hwloc_const_bitmap_t hwloc_const_cpuset_t
    A non-modifiable hwloc_cpuset_t.
    Definition: hwloc.h:142
    -
    hwloc_cpuset_t
    hwloc_bitmap_t hwloc_cpuset_t
    A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
    Definition: hwloc.h:140
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:692
    -
    hwloc_bitmap_t
    struct hwloc_bitmap_s * hwloc_bitmap_t
    Set of bits represented as an opaque pointer to an internal bitmap.
    Definition: bitmap.h:68
    -
    hwloc_linux_set_tid_cpubind
    int hwloc_linux_set_tid_cpubind(hwloc_topology_t topology, pid_t tid, hwloc_const_cpuset_t set)
    Bind a thread tid on cpus given in cpuset set.
    -
    hwloc_linux_get_tid_last_cpu_location
    int hwloc_linux_get_tid_last_cpu_location(hwloc_topology_t topology, pid_t tid, hwloc_bitmap_t set)
    Get the last physical CPU where thread tid ran.
    -
    hwloc_linux_get_tid_cpubind
    int hwloc_linux_get_tid_cpubind(hwloc_topology_t topology, pid_t tid, hwloc_cpuset_t set)
    Get the current binding of thread tid.
    -
    hwloc_linux_read_path_as_cpumask
    int hwloc_linux_read_path_as_cpumask(const char *path, hwloc_bitmap_t set)
    Convert a linux kernel cpumask file path into a hwloc bitmap set.
    -
    - - - - - - - - -
    -
    -
    linux-libnuma.h
    -
    -
    -
    1 /*
    -
    2  * Copyright © 2009 CNRS
    -
    3  * Copyright © 2009-2017 Inria. All rights reserved.
    -
    4  * Copyright © 2009-2010, 2012 Université Bordeaux
    -
    5  * See COPYING in top-level directory.
    -
    6  */
    -
    7 
    -
    15 #ifndef HWLOC_LINUX_LIBNUMA_H
    -
    16 #define HWLOC_LINUX_LIBNUMA_H
    -
    17 
    -
    18 #include "hwloc.h"
    -
    19 
    -
    20 #include <numa.h>
    -
    21 
    -
    22 
    -
    23 #ifdef __cplusplus
    -
    24 extern "C" {
    -
    25 #endif
    -
    26 
    -
    27 
    -
    54 static __hwloc_inline int
    -
    55 hwloc_cpuset_to_linux_libnuma_ulongs(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset,
    -
    56  unsigned long *mask, unsigned long *maxnode)
    -
    57 {
    -
    58  int depth = hwloc_get_type_depth(topology, HWLOC_OBJ_NUMANODE);
    -
    59  unsigned long outmaxnode = -1;
    -
    60  hwloc_obj_t node = NULL;
    -
    61 
    -
    62  /* round-up to the next ulong and clear all bytes */
    -
    63  *maxnode = (*maxnode + 8*sizeof(*mask) - 1) & ~(8*sizeof(*mask) - 1);
    -
    64  memset(mask, 0, *maxnode/8);
    -
    65 
    -
    66  while ((node = hwloc_get_next_obj_covering_cpuset_by_depth(topology, cpuset, depth, node)) != NULL) {
    -
    67  if (node->os_index >= *maxnode)
    -
    68  continue;
    -
    69  mask[node->os_index/sizeof(*mask)/8] |= 1UL << (node->os_index % (sizeof(*mask)*8));
    -
    70  if (outmaxnode == (unsigned long) -1 || outmaxnode < node->os_index)
    -
    71  outmaxnode = node->os_index;
    -
    72  }
    -
    73 
    -
    74  *maxnode = outmaxnode+1;
    -
    75  return 0;
    -
    76 }
    -
    77 
    -
    88 static __hwloc_inline int
    -
    89 hwloc_nodeset_to_linux_libnuma_ulongs(hwloc_topology_t topology, hwloc_const_nodeset_t nodeset,
    -
    90  unsigned long *mask, unsigned long *maxnode)
    -
    91 {
    -
    92  int depth = hwloc_get_type_depth(topology, HWLOC_OBJ_NUMANODE);
    -
    93  unsigned long outmaxnode = -1;
    -
    94  hwloc_obj_t node = NULL;
    -
    95 
    -
    96  /* round-up to the next ulong and clear all bytes */
    -
    97  *maxnode = (*maxnode + 8*sizeof(*mask) - 1) & ~(8*sizeof(*mask) - 1);
    -
    98  memset(mask, 0, *maxnode/8);
    -
    99 
    -
    100  while ((node = hwloc_get_next_obj_by_depth(topology, depth, node)) != NULL) {
    -
    101  if (node->os_index >= *maxnode)
    -
    102  continue;
    -
    103  if (!hwloc_bitmap_isset(nodeset, node->os_index))
    -
    104  continue;
    -
    105  mask[node->os_index/sizeof(*mask)/8] |= 1UL << (node->os_index % (sizeof(*mask)*8));
    -
    106  if (outmaxnode == (unsigned long) -1 || outmaxnode < node->os_index)
    -
    107  outmaxnode = node->os_index;
    -
    108  }
    -
    109 
    -
    110  *maxnode = outmaxnode+1;
    -
    111  return 0;
    -
    112 }
    -
    113 
    -
    123 static __hwloc_inline int
    -
    124 hwloc_cpuset_from_linux_libnuma_ulongs(hwloc_topology_t topology, hwloc_cpuset_t cpuset,
    -
    125  const unsigned long *mask, unsigned long maxnode)
    -
    126 {
    -
    127  int depth = hwloc_get_type_depth(topology, HWLOC_OBJ_NUMANODE);
    -
    128  hwloc_obj_t node = NULL;
    -
    129  hwloc_bitmap_zero(cpuset);
    -
    130  while ((node = hwloc_get_next_obj_by_depth(topology, depth, node)) != NULL)
    -
    131  if (node->os_index < maxnode
    -
    132  && (mask[node->os_index/sizeof(*mask)/8] & (1UL << (node->os_index % (sizeof(*mask)*8)))))
    -
    133  hwloc_bitmap_or(cpuset, cpuset, node->cpuset);
    -
    134  return 0;
    -
    135 }
    -
    136 
    -
    146 static __hwloc_inline int
    -
    147 hwloc_nodeset_from_linux_libnuma_ulongs(hwloc_topology_t topology, hwloc_nodeset_t nodeset,
    -
    148  const unsigned long *mask, unsigned long maxnode)
    -
    149 {
    -
    150  int depth = hwloc_get_type_depth(topology, HWLOC_OBJ_NUMANODE);
    -
    151  hwloc_obj_t node = NULL;
    -
    152  hwloc_bitmap_zero(nodeset);
    -
    153  while ((node = hwloc_get_next_obj_by_depth(topology, depth, node)) != NULL)
    -
    154  if (node->os_index < maxnode
    -
    155  && (mask[node->os_index/sizeof(*mask)/8] & (1UL << (node->os_index % (sizeof(*mask)*8)))))
    -
    156  hwloc_bitmap_set(nodeset, node->os_index);
    -
    157  return 0;
    -
    158 }
    -
    159 
    -
    189 static __hwloc_inline struct bitmask *
    -
    190 hwloc_cpuset_to_linux_libnuma_bitmask(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset) __hwloc_attribute_malloc;
    -
    191 static __hwloc_inline struct bitmask *
    -
    192 hwloc_cpuset_to_linux_libnuma_bitmask(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset)
    -
    193 {
    -
    194  int depth = hwloc_get_type_depth(topology, HWLOC_OBJ_NUMANODE);
    -
    195  hwloc_obj_t node = NULL;
    -
    196  struct bitmask *bitmask = numa_allocate_cpumask();
    -
    197  if (!bitmask)
    -
    198  return NULL;
    -
    199  while ((node = hwloc_get_next_obj_covering_cpuset_by_depth(topology, cpuset, depth, node)) != NULL)
    -
    200  if (node->attr->numanode.local_memory)
    -
    201  numa_bitmask_setbit(bitmask, node->os_index);
    -
    202  return bitmask;
    -
    203 }
    -
    204 
    -
    214 static __hwloc_inline struct bitmask *
    -
    215 hwloc_nodeset_to_linux_libnuma_bitmask(hwloc_topology_t topology, hwloc_const_nodeset_t nodeset) __hwloc_attribute_malloc;
    -
    216 static __hwloc_inline struct bitmask *
    -
    217 hwloc_nodeset_to_linux_libnuma_bitmask(hwloc_topology_t topology, hwloc_const_nodeset_t nodeset)
    -
    218 {
    -
    219  int depth = hwloc_get_type_depth(topology, HWLOC_OBJ_NUMANODE);
    -
    220  hwloc_obj_t node = NULL;
    -
    221  struct bitmask *bitmask = numa_allocate_cpumask();
    -
    222  if (!bitmask)
    -
    223  return NULL;
    -
    224  while ((node = hwloc_get_next_obj_by_depth(topology, depth, node)) != NULL)
    -
    225  if (hwloc_bitmap_isset(nodeset, node->os_index) && node->attr->numanode.local_memory)
    -
    226  numa_bitmask_setbit(bitmask, node->os_index);
    -
    227  return bitmask;
    -
    228 }
    -
    229 
    -
    235 static __hwloc_inline int
    -
    236 hwloc_cpuset_from_linux_libnuma_bitmask(hwloc_topology_t topology, hwloc_cpuset_t cpuset,
    -
    237  const struct bitmask *bitmask)
    -
    238 {
    -
    239  int depth = hwloc_get_type_depth(topology, HWLOC_OBJ_NUMANODE);
    -
    240  hwloc_obj_t node = NULL;
    -
    241  hwloc_bitmap_zero(cpuset);
    -
    242  while ((node = hwloc_get_next_obj_by_depth(topology, depth, node)) != NULL)
    -
    243  if (numa_bitmask_isbitset(bitmask, node->os_index))
    -
    244  hwloc_bitmap_or(cpuset, cpuset, node->cpuset);
    -
    245  return 0;
    -
    246 }
    -
    247 
    -
    253 static __hwloc_inline int
    -
    254 hwloc_nodeset_from_linux_libnuma_bitmask(hwloc_topology_t topology, hwloc_nodeset_t nodeset,
    -
    255  const struct bitmask *bitmask)
    -
    256 {
    -
    257  int depth = hwloc_get_type_depth(topology, HWLOC_OBJ_NUMANODE);
    -
    258  hwloc_obj_t node = NULL;
    -
    259  hwloc_bitmap_zero(nodeset);
    -
    260  while ((node = hwloc_get_next_obj_by_depth(topology, depth, node)) != NULL)
    -
    261  if (numa_bitmask_isbitset(bitmask, node->os_index))
    -
    262  hwloc_bitmap_set(nodeset, node->os_index);
    -
    263  return 0;
    -
    264 }
    -
    265 
    -
    269 #ifdef __cplusplus
    -
    270 } /* extern "C" */
    -
    271 #endif
    -
    272 
    -
    273 
    -
    274 #endif /* HWLOC_LINUX_NUMA_H */
    -
    hwloc_const_cpuset_t
    hwloc_const_bitmap_t hwloc_const_cpuset_t
    A non-modifiable hwloc_cpuset_t.
    Definition: hwloc.h:142
    -
    hwloc_const_nodeset_t
    hwloc_const_bitmap_t hwloc_const_nodeset_t
    A non-modifiable hwloc_nodeset_t.
    Definition: hwloc.h:160
    -
    hwloc_nodeset_t
    hwloc_bitmap_t hwloc_nodeset_t
    A node set is a bitmap whose bits are set according to NUMA memory node physical OS indexes.
    Definition: hwloc.h:157
    -
    hwloc_cpuset_t
    hwloc_bitmap_t hwloc_cpuset_t
    A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
    Definition: hwloc.h:140
    -
    HWLOC_OBJ_NUMANODE
    @ HWLOC_OBJ_NUMANODE
    NUMA node. An object that contains memory that is directly and byte-accessible to the host processors...
    Definition: hwloc.h:236
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:692
    -
    hwloc_get_type_depth
    int hwloc_get_type_depth(hwloc_topology_t topology, hwloc_obj_type_t type)
    Returns the depth of objects of type type.
    -
    hwloc_get_next_obj_by_depth
    static hwloc_obj_t hwloc_get_next_obj_by_depth(hwloc_topology_t topology, int depth, hwloc_obj_t prev)
    Returns the next object at depth depth.
    -
    hwloc_get_next_obj_covering_cpuset_by_depth
    static hwloc_obj_t hwloc_get_next_obj_covering_cpuset_by_depth(hwloc_topology_t topology, hwloc_const_cpuset_t set, int depth, hwloc_obj_t prev)
    Iterate through same-depth objects covering at least CPU set set.
    Definition: helper.h:321
    -
    hwloc_bitmap_set
    int hwloc_bitmap_set(hwloc_bitmap_t bitmap, unsigned id)
    Add index id in bitmap bitmap.
    -
    hwloc_bitmap_isset
    int hwloc_bitmap_isset(hwloc_const_bitmap_t bitmap, unsigned id)
    Test whether index id is part of bitmap bitmap.
    -
    hwloc_bitmap_or
    int hwloc_bitmap_or(hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
    Or bitmaps bitmap1 and bitmap2 and store the result in bitmap res.
    -
    hwloc_bitmap_zero
    void hwloc_bitmap_zero(hwloc_bitmap_t bitmap)
    Empty the bitmap bitmap.
    -
    hwloc_cpuset_from_linux_libnuma_ulongs
    static int hwloc_cpuset_from_linux_libnuma_ulongs(hwloc_topology_t topology, hwloc_cpuset_t cpuset, const unsigned long *mask, unsigned long maxnode)
    Convert the array of unsigned long mask into hwloc CPU set.
    Definition: linux-libnuma.h:124
    -
    hwloc_nodeset_to_linux_libnuma_ulongs
    static int hwloc_nodeset_to_linux_libnuma_ulongs(hwloc_topology_t topology, hwloc_const_nodeset_t nodeset, unsigned long *mask, unsigned long *maxnode)
    Convert hwloc NUMA node set nodeset into the array of unsigned long mask.
    Definition: linux-libnuma.h:89
    -
    hwloc_nodeset_from_linux_libnuma_ulongs
    static int hwloc_nodeset_from_linux_libnuma_ulongs(hwloc_topology_t topology, hwloc_nodeset_t nodeset, const unsigned long *mask, unsigned long maxnode)
    Convert the array of unsigned long mask into hwloc NUMA node set.
    Definition: linux-libnuma.h:147
    -
    hwloc_cpuset_to_linux_libnuma_ulongs
    static int hwloc_cpuset_to_linux_libnuma_ulongs(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, unsigned long *mask, unsigned long *maxnode)
    Convert hwloc CPU set cpuset into the array of unsigned long mask.
    Definition: linux-libnuma.h:55
    -
    hwloc_cpuset_from_linux_libnuma_bitmask
    static int hwloc_cpuset_from_linux_libnuma_bitmask(hwloc_topology_t topology, hwloc_cpuset_t cpuset, const struct bitmask *bitmask)
    Convert libnuma bitmask bitmask into hwloc CPU set cpuset.
    Definition: linux-libnuma.h:236
    -
    hwloc_nodeset_from_linux_libnuma_bitmask
    static int hwloc_nodeset_from_linux_libnuma_bitmask(hwloc_topology_t topology, hwloc_nodeset_t nodeset, const struct bitmask *bitmask)
    Convert libnuma bitmask bitmask into hwloc NUMA node set nodeset.
    Definition: linux-libnuma.h:254
    -
    hwloc_cpuset_to_linux_libnuma_bitmask
    static struct bitmask * hwloc_cpuset_to_linux_libnuma_bitmask(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset)
    Convert hwloc CPU set cpuset into the returned libnuma bitmask.
    Definition: linux-libnuma.h:192
    -
    hwloc_nodeset_to_linux_libnuma_bitmask
    static struct bitmask * hwloc_nodeset_to_linux_libnuma_bitmask(hwloc_topology_t topology, hwloc_const_nodeset_t nodeset)
    Convert hwloc NUMA node set nodeset into the returned libnuma bitmask.
    Definition: linux-libnuma.h:217
    -
    hwloc_obj
    Structure of a topology object.
    Definition: hwloc.h:396
    -
    hwloc_obj::os_index
    unsigned os_index
    OS-provided physical index number. It is not guaranteed unique across the entire machine,...
    Definition: hwloc.h:401
    -
    hwloc_obj::cpuset
    hwloc_cpuset_t cpuset
    CPUs covered by this object.
    Definition: hwloc.h:512
    -
    hwloc_obj::attr
    union hwloc_obj_attr_u * attr
    Object type-specific Attributes, may be NULL if no attribute value was found.
    Definition: hwloc.h:415
    -
    hwloc_obj_attr_u::numanode
    struct hwloc_obj_attr_u::hwloc_numanode_attr_s numanode
    -
    hwloc_obj_attr_u::hwloc_numanode_attr_s::local_memory
    hwloc_uint64_t local_memory
    Local memory (in bytes)
    Definition: hwloc.h:602
    -
    - - - - - - - - -
    -
    -
    windows.h
    -
    -
    -
    1 /*
    -
    2  * Copyright © 2021 Inria. All rights reserved.
    -
    3  * See COPYING in top-level directory.
    -
    4  */
    -
    5 
    -
    13 #ifndef HWLOC_WINDOWS_H
    -
    14 #define HWLOC_WINDOWS_H
    -
    15 
    -
    16 #include "hwloc.h"
    -
    17 
    -
    18 
    -
    19 #ifdef __cplusplus
    -
    20 extern "C" {
    -
    21 #endif
    -
    22 
    -
    23 
    -
    50 HWLOC_DECLSPEC int hwloc_windows_get_nr_processor_groups(hwloc_topology_t topology, unsigned long flags);
    -
    51 
    -
    66 HWLOC_DECLSPEC int hwloc_windows_get_processor_group_cpuset(hwloc_topology_t topology, unsigned pg_index, hwloc_cpuset_t cpuset, unsigned long flags);
    -
    67 
    -
    71 #ifdef __cplusplus
    -
    72 } /* extern "C" */
    -
    73 #endif
    -
    74 
    -
    75 
    -
    76 #endif /* HWLOC_WINDOWS_H */
    -
    hwloc_cpuset_t
    hwloc_bitmap_t hwloc_cpuset_t
    A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
    Definition: hwloc.h:140
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:692
    -
    hwloc_windows_get_processor_group_cpuset
    int hwloc_windows_get_processor_group_cpuset(hwloc_topology_t topology, unsigned pg_index, hwloc_cpuset_t cpuset, unsigned long flags)
    Get the CPU-set of a Windows processor group.
    -
    hwloc_windows_get_nr_processor_groups
    int hwloc_windows_get_nr_processor_groups(hwloc_topology_t topology, unsigned long flags)
    Get the number of Windows processor groups.
    -
    - - - - - - - - -
    -
    -
    glibc-sched.h
    -
    -
    -
    1 /*
    -
    2  * Copyright © 2009 CNRS
    -
    3  * Copyright © 2009-2020 Inria. All rights reserved.
    -
    4  * Copyright © 2009-2011 Université Bordeaux
    -
    5  * Copyright © 2011 Cisco Systems, Inc. All rights reserved.
    -
    6  * See COPYING in top-level directory.
    -
    7  */
    -
    8 
    -
    17 #ifndef HWLOC_GLIBC_SCHED_H
    -
    18 #define HWLOC_GLIBC_SCHED_H
    -
    19 
    -
    20 #include "hwloc.h"
    -
    21 #include "hwloc/helper.h"
    -
    22 
    -
    23 #include <assert.h>
    -
    24 
    -
    25 #if !defined _GNU_SOURCE || (!defined _SCHED_H && !defined _SCHED_H_) || (!defined CPU_SETSIZE && !defined sched_priority)
    -
    26 #error Please make sure to include sched.h before including glibc-sched.h, and define _GNU_SOURCE before any inclusion of sched.h
    -
    27 #endif
    -
    28 
    -
    29 
    -
    30 #ifdef __cplusplus
    -
    31 extern "C" {
    -
    32 #endif
    -
    33 
    -
    34 
    -
    35 #ifdef HWLOC_HAVE_CPU_SET
    -
    36 
    -
    37 
    -
    56 static __hwloc_inline int
    -
    57 hwloc_cpuset_to_glibc_sched_affinity(hwloc_topology_t topology __hwloc_attribute_unused, hwloc_const_cpuset_t hwlocset,
    -
    58  cpu_set_t *schedset, size_t schedsetsize)
    -
    59 {
    -
    60 #ifdef CPU_ZERO_S
    -
    61  unsigned cpu;
    -
    62  CPU_ZERO_S(schedsetsize, schedset);
    -
    63  hwloc_bitmap_foreach_begin(cpu, hwlocset)
    -
    64  CPU_SET_S(cpu, schedsetsize, schedset);
    -
    65  hwloc_bitmap_foreach_end();
    -
    66 #else /* !CPU_ZERO_S */
    -
    67  unsigned cpu;
    -
    68  CPU_ZERO(schedset);
    -
    69  assert(schedsetsize == sizeof(cpu_set_t));
    -
    70  hwloc_bitmap_foreach_begin(cpu, hwlocset)
    -
    71  CPU_SET(cpu, schedset);
    -
    72  hwloc_bitmap_foreach_end();
    -
    73 #endif /* !CPU_ZERO_S */
    -
    74  return 0;
    -
    75 }
    -
    76 
    -
    84 static __hwloc_inline int
    -
    85 hwloc_cpuset_from_glibc_sched_affinity(hwloc_topology_t topology __hwloc_attribute_unused, hwloc_cpuset_t hwlocset,
    -
    86  const cpu_set_t *schedset, size_t schedsetsize)
    -
    87 {
    -
    88  int cpu;
    -
    89 #ifdef CPU_ZERO_S
    -
    90  int count;
    -
    91 #endif
    -
    92  hwloc_bitmap_zero(hwlocset);
    -
    93 #ifdef CPU_ZERO_S
    -
    94  count = CPU_COUNT_S(schedsetsize, schedset);
    -
    95  cpu = 0;
    -
    96  while (count) {
    -
    97  if (CPU_ISSET_S(cpu, schedsetsize, schedset)) {
    -
    98  hwloc_bitmap_set(hwlocset, cpu);
    -
    99  count--;
    -
    100  }
    -
    101  cpu++;
    -
    102  }
    -
    103 #else /* !CPU_ZERO_S */
    -
    104  /* sched.h does not support dynamic cpu_set_t (introduced in glibc 2.7),
    -
    105  * assume we have a very old interface without CPU_COUNT (added in 2.6)
    -
    106  */
    -
    107  assert(schedsetsize == sizeof(cpu_set_t));
    -
    108  for(cpu=0; cpu<CPU_SETSIZE; cpu++)
    -
    109  if (CPU_ISSET(cpu, schedset))
    -
    110  hwloc_bitmap_set(hwlocset, cpu);
    -
    111 #endif /* !CPU_ZERO_S */
    -
    112  return 0;
    -
    113 }
    -
    114 
    -
    118 #endif /* CPU_SET */
    -
    119 
    -
    120 
    -
    121 #ifdef __cplusplus
    -
    122 } /* extern "C" */
    -
    123 #endif
    -
    124 
    -
    125 
    -
    126 #endif /* HWLOC_GLIBC_SCHED_H */
    -
    hwloc_const_cpuset_t
    hwloc_const_bitmap_t hwloc_const_cpuset_t
    A non-modifiable hwloc_cpuset_t.
    Definition: hwloc.h:142
    -
    hwloc_cpuset_t
    hwloc_bitmap_t hwloc_cpuset_t
    A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
    Definition: hwloc.h:140
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:692
    -
    hwloc_bitmap_set
    int hwloc_bitmap_set(hwloc_bitmap_t bitmap, unsigned id)
    Add index id in bitmap bitmap.
    -
    hwloc_bitmap_foreach_begin
    #define hwloc_bitmap_foreach_begin(id, bitmap)
    Loop macro iterating on bitmap bitmap.
    Definition: bitmap.h:370
    -
    hwloc_bitmap_zero
    void hwloc_bitmap_zero(hwloc_bitmap_t bitmap)
    Empty the bitmap bitmap.
    -
    hwloc_bitmap_foreach_end
    #define hwloc_bitmap_foreach_end()
    End of loop macro iterating on a bitmap.
    Definition: bitmap.h:384
    -
    hwloc_cpuset_to_glibc_sched_affinity
    static int hwloc_cpuset_to_glibc_sched_affinity(hwloc_topology_t topology, hwloc_const_cpuset_t hwlocset, cpu_set_t *schedset, size_t schedsetsize)
    Convert hwloc CPU set toposet into glibc sched affinity CPU set schedset.
    Definition: glibc-sched.h:57
    -
    hwloc_cpuset_from_glibc_sched_affinity
    static int hwloc_cpuset_from_glibc_sched_affinity(hwloc_topology_t topology, hwloc_cpuset_t hwlocset, const cpu_set_t *schedset, size_t schedsetsize)
    Convert glibc sched affinity CPU set schedset into hwloc CPU set.
    Definition: glibc-sched.h:85
    -
    - - - - - - - - -
    -
    -
    opencl.h
    -
    -
    -
    1 /*
    -
    2  * Copyright © 2012-2021 Inria. All rights reserved.
    -
    3  * Copyright © 2013, 2018 Université Bordeaux. All right reserved.
    -
    4  * See COPYING in top-level directory.
    -
    5  */
    -
    6 
    -
    14 #ifndef HWLOC_OPENCL_H
    -
    15 #define HWLOC_OPENCL_H
    -
    16 
    -
    17 #include "hwloc.h"
    -
    18 #include "hwloc/autogen/config.h"
    -
    19 #include "hwloc/helper.h"
    -
    20 #ifdef HWLOC_LINUX_SYS
    -
    21 #include "hwloc/linux.h"
    -
    22 #endif
    -
    23 
    -
    24 #ifdef __APPLE__
    -
    25 #include <OpenCL/cl.h>
    -
    26 #else
    -
    27 #include <CL/cl.h>
    -
    28 #endif
    -
    29 
    -
    30 #include <stdio.h>
    -
    31 
    -
    32 
    -
    33 #ifdef __cplusplus
    -
    34 extern "C" {
    -
    35 #endif
    -
    36 
    -
    37 
    -
    38 /* OpenCL extensions aren't always shipped with default headers, and
    -
    39  * they don't always reflect what the installed implementations support.
    -
    40  * Try everything and let the implementation return errors when non supported.
    -
    41  */
    -
    42 /* Copyright (c) 2008-2018 The Khronos Group Inc. */
    -
    43 
    -
    44 /* needs "cl_amd_device_attribute_query" device extension, but not strictly required for clGetDeviceInfo() */
    -
    45 #define HWLOC_CL_DEVICE_TOPOLOGY_AMD 0x4037
    -
    46 typedef union {
    -
    47  struct { cl_uint type; cl_uint data[5]; } raw;
    -
    48  struct { cl_uint type; cl_char unused[17]; cl_char bus; cl_char device; cl_char function; } pcie;
    -
    49 } hwloc_cl_device_topology_amd;
    -
    50 #define HWLOC_CL_DEVICE_TOPOLOGY_TYPE_PCIE_AMD 1
    -
    51 
    -
    52 /* needs "cl_nv_device_attribute_query" device extension, but not strictly required for clGetDeviceInfo() */
    -
    53 #define HWLOC_CL_DEVICE_PCI_BUS_ID_NV 0x4008
    -
    54 #define HWLOC_CL_DEVICE_PCI_SLOT_ID_NV 0x4009
    -
    55 #define HWLOC_CL_DEVICE_PCI_DOMAIN_ID_NV 0x400A
    -
    56 
    -
    57 
    -
    73 static __hwloc_inline int
    -
    74 hwloc_opencl_get_device_pci_busid(cl_device_id device,
    -
    75  unsigned *domain, unsigned *bus, unsigned *dev, unsigned *func)
    -
    76 {
    -
    77  hwloc_cl_device_topology_amd amdtopo;
    -
    78  cl_uint nvbus, nvslot, nvdomain;
    -
    79  cl_int clret;
    -
    80 
    -
    81  clret = clGetDeviceInfo(device, HWLOC_CL_DEVICE_TOPOLOGY_AMD, sizeof(amdtopo), &amdtopo, NULL);
    -
    82  if (CL_SUCCESS == clret
    -
    83  && HWLOC_CL_DEVICE_TOPOLOGY_TYPE_PCIE_AMD == amdtopo.raw.type) {
    -
    84  *domain = 0; /* can't do anything better */
    -
    85  /* cl_device_topology_amd stores bus ID in cl_char, dont convert those signed char directly to unsigned int */
    -
    86  *bus = (unsigned) (unsigned char) amdtopo.pcie.bus;
    -
    87  *dev = (unsigned) (unsigned char) amdtopo.pcie.device;
    -
    88  *func = (unsigned) (unsigned char) amdtopo.pcie.function;
    -
    89  return 0;
    -
    90  }
    -
    91 
    -
    92  clret = clGetDeviceInfo(device, HWLOC_CL_DEVICE_PCI_BUS_ID_NV, sizeof(nvbus), &nvbus, NULL);
    -
    93  if (CL_SUCCESS == clret) {
    -
    94  clret = clGetDeviceInfo(device, HWLOC_CL_DEVICE_PCI_SLOT_ID_NV, sizeof(nvslot), &nvslot, NULL);
    -
    95  if (CL_SUCCESS == clret) {
    -
    96  clret = clGetDeviceInfo(device, HWLOC_CL_DEVICE_PCI_DOMAIN_ID_NV, sizeof(nvdomain), &nvdomain, NULL);
    -
    97  if (CL_SUCCESS == clret) { /* available since CUDA 10.2 */
    -
    98  *domain = nvdomain;
    -
    99  } else {
    -
    100  *domain = 0;
    -
    101  }
    -
    102  *bus = nvbus & 0xff;
    -
    103  /* non-documented but used in many other projects */
    -
    104  *dev = nvslot >> 3;
    -
    105  *func = nvslot & 0x7;
    -
    106  return 0;
    -
    107  }
    -
    108  }
    -
    109 
    -
    110  return -1;
    -
    111 }
    -
    112 
    -
    130 static __hwloc_inline int
    -
    131 hwloc_opencl_get_device_cpuset(hwloc_topology_t topology __hwloc_attribute_unused,
    -
    132  cl_device_id device __hwloc_attribute_unused,
    -
    133  hwloc_cpuset_t set)
    -
    134 {
    -
    135 #if (defined HWLOC_LINUX_SYS)
    -
    136  /* If we're on Linux, try AMD/NVIDIA extensions + the sysfs mechanism to get the local cpus */
    -
    137 #define HWLOC_OPENCL_DEVICE_SYSFS_PATH_MAX 128
    -
    138  char path[HWLOC_OPENCL_DEVICE_SYSFS_PATH_MAX];
    -
    139  unsigned pcidomain, pcibus, pcidev, pcifunc;
    -
    140 
    -
    141  if (!hwloc_topology_is_thissystem(topology)) {
    -
    142  errno = EINVAL;
    -
    143  return -1;
    -
    144  }
    -
    145 
    -
    146  if (hwloc_opencl_get_device_pci_busid(device, &pcidomain, &pcibus, &pcidev, &pcifunc) < 0) {
    -
    147  hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
    -
    148  return 0;
    -
    149  }
    -
    150 
    -
    151  sprintf(path, "/sys/bus/pci/devices/%04x:%02x:%02x.%01x/local_cpus", pcidomain, pcibus, pcidev, pcifunc);
    -
    152  if (hwloc_linux_read_path_as_cpumask(path, set) < 0
    -
    153  || hwloc_bitmap_iszero(set))
    -
    154  hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
    -
    155 #else
    -
    156  /* Non-Linux systems simply get a full cpuset */
    -
    157  hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
    -
    158 #endif
    -
    159  return 0;
    -
    160 }
    -
    161 
    -
    177 static __hwloc_inline hwloc_obj_t
    -
    178 hwloc_opencl_get_device_osdev_by_index(hwloc_topology_t topology,
    -
    179  unsigned platform_index, unsigned device_index)
    -
    180 {
    -
    181  unsigned x = (unsigned) -1, y = (unsigned) -1;
    -
    182  hwloc_obj_t osdev = NULL;
    -
    183  while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
    -
    184  if (HWLOC_OBJ_OSDEV_COPROC == osdev->attr->osdev.type
    -
    185  && osdev->name
    -
    186  && sscanf(osdev->name, "opencl%ud%u", &x, &y) == 2
    -
    187  && platform_index == x && device_index == y)
    -
    188  return osdev;
    -
    189  }
    -
    190  return NULL;
    -
    191 }
    -
    192 
    -
    214 static __hwloc_inline hwloc_obj_t
    -
    215 hwloc_opencl_get_device_osdev(hwloc_topology_t topology __hwloc_attribute_unused,
    -
    216  cl_device_id device __hwloc_attribute_unused)
    -
    217 {
    -
    218  hwloc_obj_t osdev;
    -
    219  unsigned pcidomain, pcibus, pcidevice, pcifunc;
    -
    220 
    -
    221  if (hwloc_opencl_get_device_pci_busid(device, &pcidomain, &pcibus, &pcidevice, &pcifunc) < 0) {
    -
    222  errno = EINVAL;
    -
    223  return NULL;
    -
    224  }
    -
    225 
    -
    226  osdev = NULL;
    -
    227  while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
    -
    228  hwloc_obj_t pcidev = osdev->parent;
    -
    229  if (strncmp(osdev->name, "opencl", 6))
    -
    230  continue;
    -
    231  if (pcidev
    -
    232  && pcidev->type == HWLOC_OBJ_PCI_DEVICE
    -
    233  && pcidev->attr->pcidev.domain == pcidomain
    -
    234  && pcidev->attr->pcidev.bus == pcibus
    -
    235  && pcidev->attr->pcidev.dev == pcidevice
    -
    236  && pcidev->attr->pcidev.func == pcifunc)
    -
    237  return osdev;
    -
    238  /* if PCI are filtered out, we need a info attr to match on */
    -
    239  }
    -
    240 
    -
    241  return NULL;
    -
    242 }
    -
    243 
    -
    247 #ifdef __cplusplus
    -
    248 } /* extern "C" */
    -
    249 #endif
    -
    250 
    -
    251 
    -
    252 #endif /* HWLOC_OPENCL_H */
    -
    hwloc_cpuset_t
    hwloc_bitmap_t hwloc_cpuset_t
    A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
    Definition: hwloc.h:140
    -
    HWLOC_OBJ_OSDEV_COPROC
    @ HWLOC_OBJ_OSDEV_COPROC
    Operating system co-processor device. For instance "opencl0d0" for a OpenCL device,...
    Definition: hwloc.h:353
    -
    HWLOC_OBJ_PCI_DEVICE
    @ HWLOC_OBJ_PCI_DEVICE
    PCI device (filtered out by default).
    Definition: hwloc.h:269
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:692
    -
    hwloc_topology_is_thissystem
    int hwloc_topology_is_thissystem(hwloc_topology_t restrict topology)
    Does the topology context come from this system?
    -
    hwloc_topology_get_complete_cpuset
    hwloc_const_cpuset_t hwloc_topology_get_complete_cpuset(hwloc_topology_t topology)
    Get complete CPU set.
    -
    hwloc_get_next_osdev
    static hwloc_obj_t hwloc_get_next_osdev(hwloc_topology_t topology, hwloc_obj_t prev)
    Get the next OS device in the system.
    Definition: helper.h:1191
    -
    hwloc_bitmap_iszero
    int hwloc_bitmap_iszero(hwloc_const_bitmap_t bitmap)
    Test whether bitmap bitmap is empty.
    -
    hwloc_bitmap_copy
    int hwloc_bitmap_copy(hwloc_bitmap_t dst, hwloc_const_bitmap_t src)
    Copy the contents of bitmap src into the already allocated bitmap dst.
    -
    hwloc_linux_read_path_as_cpumask
    int hwloc_linux_read_path_as_cpumask(const char *path, hwloc_bitmap_t set)
    Convert a linux kernel cpumask file path into a hwloc bitmap set.
    -
    hwloc_opencl_get_device_pci_busid
    static int hwloc_opencl_get_device_pci_busid(cl_device_id device, unsigned *domain, unsigned *bus, unsigned *dev, unsigned *func)
    Return the domain, bus and device IDs of the OpenCL device device.
    Definition: opencl.h:74
    -
    hwloc_opencl_get_device_cpuset
    static int hwloc_opencl_get_device_cpuset(hwloc_topology_t topology, cl_device_id device, hwloc_cpuset_t set)
    Get the CPU set of processors that are physically close to OpenCL device device.
    Definition: opencl.h:131
    -
    hwloc_opencl_get_device_osdev
    static hwloc_obj_t hwloc_opencl_get_device_osdev(hwloc_topology_t topology, cl_device_id device)
    Get the hwloc OS device object corresponding to OpenCL device deviceX.
    Definition: opencl.h:215
    -
    hwloc_opencl_get_device_osdev_by_index
    static hwloc_obj_t hwloc_opencl_get_device_osdev_by_index(hwloc_topology_t topology, unsigned platform_index, unsigned device_index)
    Get the hwloc OS device object corresponding to the OpenCL device for the given indexes.
    Definition: opencl.h:178
    -
    hwloc_obj
    Structure of a topology object.
    Definition: hwloc.h:396
    -
    hwloc_obj::name
    char * name
    Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name str...
    Definition: hwloc.h:408
    -
    hwloc_obj::type
    hwloc_obj_type_t type
    Type of object.
    Definition: hwloc.h:398
    -
    hwloc_obj::attr
    union hwloc_obj_attr_u * attr
    Object type-specific Attributes, may be NULL if no attribute value was found.
    Definition: hwloc.h:415
    -
    hwloc_obj::parent
    struct hwloc_obj * parent
    Parent, NULL if root (Machine object)
    Definition: hwloc.h:446
    -
    hwloc_obj_attr_u::pcidev
    struct hwloc_obj_attr_u::hwloc_pcidev_attr_s pcidev
    -
    hwloc_obj_attr_u::osdev
    struct hwloc_obj_attr_u::hwloc_osdev_attr_s osdev
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::dev
    unsigned char dev
    Definition: hwloc.h:639
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::func
    unsigned char func
    Definition: hwloc.h:639
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::domain
    unsigned short domain
    Definition: hwloc.h:635
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::bus
    unsigned char bus
    Definition: hwloc.h:639
    -
    hwloc_obj_attr_u::hwloc_osdev_attr_s::type
    hwloc_obj_osdev_type_t type
    Definition: hwloc.h:666
    -
    hwloc_cl_device_topology_amd
    Definition: opencl.h:46
    -
    hwloc_cl_device_topology_amd::device
    cl_char device
    Definition: opencl.h:48
    -
    hwloc_cl_device_topology_amd::pcie
    struct hwloc_cl_device_topology_amd::@4 pcie
    -
    hwloc_cl_device_topology_amd::bus
    cl_char bus
    Definition: opencl.h:48
    -
    hwloc_cl_device_topology_amd::function
    cl_char function
    Definition: opencl.h:48
    -
    hwloc_cl_device_topology_amd::raw
    struct hwloc_cl_device_topology_amd::@3 raw
    -
    hwloc_cl_device_topology_amd::type
    cl_uint type
    Definition: opencl.h:47
    -
    - - - - - - - - -
    -
    -
    cuda.h
    -
    -
    -
    1 /*
    -
    2  * Copyright © 2010-2021 Inria. All rights reserved.
    -
    3  * Copyright © 2010-2011 Université Bordeaux
    -
    4  * Copyright © 2011 Cisco Systems, Inc. All rights reserved.
    -
    5  * See COPYING in top-level directory.
    -
    6  */
    -
    7 
    -
    16 #ifndef HWLOC_CUDA_H
    -
    17 #define HWLOC_CUDA_H
    -
    18 
    -
    19 #include "hwloc.h"
    -
    20 #include "hwloc/autogen/config.h"
    -
    21 #include "hwloc/helper.h"
    -
    22 #ifdef HWLOC_LINUX_SYS
    -
    23 #include "hwloc/linux.h"
    -
    24 #endif
    -
    25 
    -
    26 #include <cuda.h>
    -
    27 
    -
    28 
    -
    29 #ifdef __cplusplus
    -
    30 extern "C" {
    -
    31 #endif
    -
    32 
    -
    33 
    -
    46 static __hwloc_inline int
    -
    47 hwloc_cuda_get_device_pci_ids(hwloc_topology_t topology __hwloc_attribute_unused,
    -
    48  CUdevice cudevice, int *domain, int *bus, int *dev)
    -
    49 {
    -
    50  CUresult cres;
    -
    51 
    -
    52 #if CUDA_VERSION >= 4000
    -
    53  cres = cuDeviceGetAttribute(domain, CU_DEVICE_ATTRIBUTE_PCI_DOMAIN_ID, cudevice);
    -
    54  if (cres != CUDA_SUCCESS) {
    -
    55  errno = ENOSYS;
    -
    56  return -1;
    -
    57  }
    -
    58 #else
    -
    59  *domain = 0;
    -
    60 #endif
    -
    61  cres = cuDeviceGetAttribute(bus, CU_DEVICE_ATTRIBUTE_PCI_BUS_ID, cudevice);
    -
    62  if (cres != CUDA_SUCCESS) {
    -
    63  errno = ENOSYS;
    -
    64  return -1;
    -
    65  }
    -
    66  cres = cuDeviceGetAttribute(dev, CU_DEVICE_ATTRIBUTE_PCI_DEVICE_ID, cudevice);
    -
    67  if (cres != CUDA_SUCCESS) {
    -
    68  errno = ENOSYS;
    -
    69  return -1;
    -
    70  }
    -
    71 
    -
    72  return 0;
    -
    73 }
    -
    74 
    -
    91 static __hwloc_inline int
    -
    92 hwloc_cuda_get_device_cpuset(hwloc_topology_t topology __hwloc_attribute_unused,
    -
    93  CUdevice cudevice, hwloc_cpuset_t set)
    -
    94 {
    -
    95 #ifdef HWLOC_LINUX_SYS
    -
    96  /* If we're on Linux, use the sysfs mechanism to get the local cpus */
    -
    97 #define HWLOC_CUDA_DEVICE_SYSFS_PATH_MAX 128
    -
    98  char path[HWLOC_CUDA_DEVICE_SYSFS_PATH_MAX];
    -
    99  int domainid, busid, deviceid;
    -
    100 
    -
    101  if (hwloc_cuda_get_device_pci_ids(topology, cudevice, &domainid, &busid, &deviceid))
    -
    102  return -1;
    -
    103 
    -
    104  if (!hwloc_topology_is_thissystem(topology)) {
    -
    105  errno = EINVAL;
    -
    106  return -1;
    -
    107  }
    -
    108 
    -
    109  sprintf(path, "/sys/bus/pci/devices/%04x:%02x:%02x.0/local_cpus", domainid, busid, deviceid);
    -
    110  if (hwloc_linux_read_path_as_cpumask(path, set) < 0
    -
    111  || hwloc_bitmap_iszero(set))
    -
    112  hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
    -
    113 #else
    -
    114  /* Non-Linux systems simply get a full cpuset */
    -
    115  hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
    -
    116 #endif
    -
    117  return 0;
    -
    118 }
    -
    119 
    -
    130 static __hwloc_inline hwloc_obj_t
    -
    131 hwloc_cuda_get_device_pcidev(hwloc_topology_t topology, CUdevice cudevice)
    -
    132 {
    -
    133  int domain, bus, dev;
    -
    134 
    -
    135  if (hwloc_cuda_get_device_pci_ids(topology, cudevice, &domain, &bus, &dev))
    -
    136  return NULL;
    -
    137 
    -
    138  return hwloc_get_pcidev_by_busid(topology, domain, bus, dev, 0);
    -
    139 }
    -
    140 
    -
    156 static __hwloc_inline hwloc_obj_t
    -
    157 hwloc_cuda_get_device_osdev(hwloc_topology_t topology, CUdevice cudevice)
    -
    158 {
    -
    159  hwloc_obj_t osdev = NULL;
    -
    160  int domain, bus, dev;
    -
    161 
    -
    162  if (hwloc_cuda_get_device_pci_ids(topology, cudevice, &domain, &bus, &dev))
    -
    163  return NULL;
    -
    164 
    -
    165  osdev = NULL;
    -
    166  while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
    -
    167  hwloc_obj_t pcidev = osdev->parent;
    -
    168  if (strncmp(osdev->name, "cuda", 4))
    -
    169  continue;
    -
    170  if (pcidev
    -
    171  && pcidev->type == HWLOC_OBJ_PCI_DEVICE
    -
    172  && (int) pcidev->attr->pcidev.domain == domain
    -
    173  && (int) pcidev->attr->pcidev.bus == bus
    -
    174  && (int) pcidev->attr->pcidev.dev == dev
    -
    175  && pcidev->attr->pcidev.func == 0)
    -
    176  return osdev;
    -
    177  /* if PCI are filtered out, we need a info attr to match on */
    -
    178  }
    -
    179 
    -
    180  return NULL;
    -
    181 }
    -
    182 
    -
    198 static __hwloc_inline hwloc_obj_t
    -
    199 hwloc_cuda_get_device_osdev_by_index(hwloc_topology_t topology, unsigned idx)
    -
    200 {
    -
    201  hwloc_obj_t osdev = NULL;
    -
    202  while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
    -
    203  if (HWLOC_OBJ_OSDEV_COPROC == osdev->attr->osdev.type
    -
    204  && osdev->name
    -
    205  && !strncmp("cuda", osdev->name, 4)
    -
    206  && atoi(osdev->name + 4) == (int) idx)
    -
    207  return osdev;
    -
    208  }
    -
    209  return NULL;
    -
    210 }
    -
    211 
    -
    215 #ifdef __cplusplus
    -
    216 } /* extern "C" */
    -
    217 #endif
    -
    218 
    -
    219 
    -
    220 #endif /* HWLOC_CUDA_H */
    -
    hwloc_cpuset_t
    hwloc_bitmap_t hwloc_cpuset_t
    A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
    Definition: hwloc.h:140
    -
    HWLOC_OBJ_OSDEV_COPROC
    @ HWLOC_OBJ_OSDEV_COPROC
    Operating system co-processor device. For instance "opencl0d0" for a OpenCL device,...
    Definition: hwloc.h:353
    -
    HWLOC_OBJ_PCI_DEVICE
    @ HWLOC_OBJ_PCI_DEVICE
    PCI device (filtered out by default).
    Definition: hwloc.h:269
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:692
    -
    hwloc_topology_is_thissystem
    int hwloc_topology_is_thissystem(hwloc_topology_t restrict topology)
    Does the topology context come from this system?
    -
    hwloc_topology_get_complete_cpuset
    hwloc_const_cpuset_t hwloc_topology_get_complete_cpuset(hwloc_topology_t topology)
    Get complete CPU set.
    -
    hwloc_get_next_osdev
    static hwloc_obj_t hwloc_get_next_osdev(hwloc_topology_t topology, hwloc_obj_t prev)
    Get the next OS device in the system.
    Definition: helper.h:1191
    -
    hwloc_get_pcidev_by_busid
    static hwloc_obj_t hwloc_get_pcidev_by_busid(hwloc_topology_t topology, unsigned domain, unsigned bus, unsigned dev, unsigned func)
    Find the PCI device object matching the PCI bus id given domain, bus device and function PCI bus id.
    Definition: helper.h:1154
    -
    hwloc_bitmap_iszero
    int hwloc_bitmap_iszero(hwloc_const_bitmap_t bitmap)
    Test whether bitmap bitmap is empty.
    -
    hwloc_bitmap_copy
    int hwloc_bitmap_copy(hwloc_bitmap_t dst, hwloc_const_bitmap_t src)
    Copy the contents of bitmap src into the already allocated bitmap dst.
    -
    hwloc_linux_read_path_as_cpumask
    int hwloc_linux_read_path_as_cpumask(const char *path, hwloc_bitmap_t set)
    Convert a linux kernel cpumask file path into a hwloc bitmap set.
    -
    hwloc_cuda_get_device_pci_ids
    static int hwloc_cuda_get_device_pci_ids(hwloc_topology_t topology, CUdevice cudevice, int *domain, int *bus, int *dev)
    Return the domain, bus and device IDs of the CUDA device cudevice.
    Definition: cuda.h:47
    -
    hwloc_cuda_get_device_pcidev
    static hwloc_obj_t hwloc_cuda_get_device_pcidev(hwloc_topology_t topology, CUdevice cudevice)
    Get the hwloc PCI device object corresponding to the CUDA device cudevice.
    Definition: cuda.h:131
    -
    hwloc_cuda_get_device_osdev_by_index
    static hwloc_obj_t hwloc_cuda_get_device_osdev_by_index(hwloc_topology_t topology, unsigned idx)
    Get the hwloc OS device object corresponding to the CUDA device whose index is idx.
    Definition: cuda.h:199
    -
    hwloc_cuda_get_device_osdev
    static hwloc_obj_t hwloc_cuda_get_device_osdev(hwloc_topology_t topology, CUdevice cudevice)
    Get the hwloc OS device object corresponding to CUDA device cudevice.
    Definition: cuda.h:157
    -
    hwloc_cuda_get_device_cpuset
    static int hwloc_cuda_get_device_cpuset(hwloc_topology_t topology, CUdevice cudevice, hwloc_cpuset_t set)
    Get the CPU set of processors that are physically close to device cudevice.
    Definition: cuda.h:92
    -
    hwloc_obj
    Structure of a topology object.
    Definition: hwloc.h:396
    -
    hwloc_obj::name
    char * name
    Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name str...
    Definition: hwloc.h:408
    -
    hwloc_obj::type
    hwloc_obj_type_t type
    Type of object.
    Definition: hwloc.h:398
    -
    hwloc_obj::attr
    union hwloc_obj_attr_u * attr
    Object type-specific Attributes, may be NULL if no attribute value was found.
    Definition: hwloc.h:415
    -
    hwloc_obj::parent
    struct hwloc_obj * parent
    Parent, NULL if root (Machine object)
    Definition: hwloc.h:446
    -
    hwloc_obj_attr_u::pcidev
    struct hwloc_obj_attr_u::hwloc_pcidev_attr_s pcidev
    -
    hwloc_obj_attr_u::osdev
    struct hwloc_obj_attr_u::hwloc_osdev_attr_s osdev
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::dev
    unsigned char dev
    Definition: hwloc.h:639
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::func
    unsigned char func
    Definition: hwloc.h:639
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::domain
    unsigned short domain
    Definition: hwloc.h:635
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::bus
    unsigned char bus
    Definition: hwloc.h:639
    -
    hwloc_obj_attr_u::hwloc_osdev_attr_s::type
    hwloc_obj_osdev_type_t type
    Definition: hwloc.h:666
    -
    - - - - - - - - -
    -
    -
    cudart.h
    -
    -
    -
    1 /*
    -
    2  * Copyright © 2010-2021 Inria. All rights reserved.
    -
    3  * Copyright © 2010-2011 Université Bordeaux
    -
    4  * Copyright © 2011 Cisco Systems, Inc. All rights reserved.
    -
    5  * See COPYING in top-level directory.
    -
    6  */
    -
    7 
    -
    16 #ifndef HWLOC_CUDART_H
    -
    17 #define HWLOC_CUDART_H
    -
    18 
    -
    19 #include "hwloc.h"
    -
    20 #include "hwloc/autogen/config.h"
    -
    21 #include "hwloc/helper.h"
    -
    22 #ifdef HWLOC_LINUX_SYS
    -
    23 #include "hwloc/linux.h"
    -
    24 #endif
    -
    25 
    -
    26 #include <cuda.h> /* for CUDA_VERSION */
    -
    27 #include <cuda_runtime_api.h>
    -
    28 
    -
    29 
    -
    30 #ifdef __cplusplus
    -
    31 extern "C" {
    -
    32 #endif
    -
    33 
    -
    34 
    -
    47 static __hwloc_inline int
    -
    48 hwloc_cudart_get_device_pci_ids(hwloc_topology_t topology __hwloc_attribute_unused,
    -
    49  int idx, int *domain, int *bus, int *dev)
    -
    50 {
    -
    51  cudaError_t cerr;
    -
    52  struct cudaDeviceProp prop;
    -
    53 
    -
    54  cerr = cudaGetDeviceProperties(&prop, idx);
    -
    55  if (cerr) {
    -
    56  errno = ENOSYS;
    -
    57  return -1;
    -
    58  }
    -
    59 
    -
    60 #if CUDA_VERSION >= 4000
    -
    61  *domain = prop.pciDomainID;
    -
    62 #else
    -
    63  *domain = 0;
    -
    64 #endif
    -
    65 
    -
    66  *bus = prop.pciBusID;
    -
    67  *dev = prop.pciDeviceID;
    -
    68 
    -
    69  return 0;
    -
    70 }
    -
    71 
    -
    88 static __hwloc_inline int
    -
    89 hwloc_cudart_get_device_cpuset(hwloc_topology_t topology __hwloc_attribute_unused,
    -
    90  int idx, hwloc_cpuset_t set)
    -
    91 {
    -
    92 #ifdef HWLOC_LINUX_SYS
    -
    93  /* If we're on Linux, use the sysfs mechanism to get the local cpus */
    -
    94 #define HWLOC_CUDART_DEVICE_SYSFS_PATH_MAX 128
    -
    95  char path[HWLOC_CUDART_DEVICE_SYSFS_PATH_MAX];
    -
    96  int domain, bus, dev;
    -
    97 
    -
    98  if (hwloc_cudart_get_device_pci_ids(topology, idx, &domain, &bus, &dev))
    -
    99  return -1;
    -
    100 
    -
    101  if (!hwloc_topology_is_thissystem(topology)) {
    -
    102  errno = EINVAL;
    -
    103  return -1;
    -
    104  }
    -
    105 
    -
    106  sprintf(path, "/sys/bus/pci/devices/%04x:%02x:%02x.0/local_cpus", (unsigned) domain, (unsigned) bus, (unsigned) dev);
    -
    107  if (hwloc_linux_read_path_as_cpumask(path, set) < 0
    -
    108  || hwloc_bitmap_iszero(set))
    -
    109  hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
    -
    110 #else
    -
    111  /* Non-Linux systems simply get a full cpuset */
    -
    112  hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
    -
    113 #endif
    -
    114  return 0;
    -
    115 }
    -
    116 
    -
    127 static __hwloc_inline hwloc_obj_t
    -
    128 hwloc_cudart_get_device_pcidev(hwloc_topology_t topology, int idx)
    -
    129 {
    -
    130  int domain, bus, dev;
    -
    131 
    -
    132  if (hwloc_cudart_get_device_pci_ids(topology, idx, &domain, &bus, &dev))
    -
    133  return NULL;
    -
    134 
    -
    135  return hwloc_get_pcidev_by_busid(topology, domain, bus, dev, 0);
    -
    136 }
    -
    137 
    -
    155 static __hwloc_inline hwloc_obj_t
    -
    156 hwloc_cudart_get_device_osdev_by_index(hwloc_topology_t topology, unsigned idx)
    -
    157 {
    -
    158  hwloc_obj_t osdev = NULL;
    -
    159  while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
    -
    160  if (HWLOC_OBJ_OSDEV_COPROC == osdev->attr->osdev.type
    -
    161  && osdev->name
    -
    162  && !strncmp("cuda", osdev->name, 4)
    -
    163  && atoi(osdev->name + 4) == (int) idx)
    -
    164  return osdev;
    -
    165  }
    -
    166  return NULL;
    -
    167 }
    -
    168 
    -
    172 #ifdef __cplusplus
    -
    173 } /* extern "C" */
    -
    174 #endif
    -
    175 
    -
    176 
    -
    177 #endif /* HWLOC_CUDART_H */
    -
    hwloc_cpuset_t
    hwloc_bitmap_t hwloc_cpuset_t
    A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
    Definition: hwloc.h:140
    -
    HWLOC_OBJ_OSDEV_COPROC
    @ HWLOC_OBJ_OSDEV_COPROC
    Operating system co-processor device. For instance "opencl0d0" for a OpenCL device,...
    Definition: hwloc.h:353
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:692
    -
    hwloc_topology_is_thissystem
    int hwloc_topology_is_thissystem(hwloc_topology_t restrict topology)
    Does the topology context come from this system?
    -
    hwloc_topology_get_complete_cpuset
    hwloc_const_cpuset_t hwloc_topology_get_complete_cpuset(hwloc_topology_t topology)
    Get complete CPU set.
    -
    hwloc_get_next_osdev
    static hwloc_obj_t hwloc_get_next_osdev(hwloc_topology_t topology, hwloc_obj_t prev)
    Get the next OS device in the system.
    Definition: helper.h:1191
    -
    hwloc_get_pcidev_by_busid
    static hwloc_obj_t hwloc_get_pcidev_by_busid(hwloc_topology_t topology, unsigned domain, unsigned bus, unsigned dev, unsigned func)
    Find the PCI device object matching the PCI bus id given domain, bus device and function PCI bus id.
    Definition: helper.h:1154
    -
    hwloc_bitmap_iszero
    int hwloc_bitmap_iszero(hwloc_const_bitmap_t bitmap)
    Test whether bitmap bitmap is empty.
    -
    hwloc_bitmap_copy
    int hwloc_bitmap_copy(hwloc_bitmap_t dst, hwloc_const_bitmap_t src)
    Copy the contents of bitmap src into the already allocated bitmap dst.
    -
    hwloc_linux_read_path_as_cpumask
    int hwloc_linux_read_path_as_cpumask(const char *path, hwloc_bitmap_t set)
    Convert a linux kernel cpumask file path into a hwloc bitmap set.
    -
    hwloc_cudart_get_device_cpuset
    static int hwloc_cudart_get_device_cpuset(hwloc_topology_t topology, int idx, hwloc_cpuset_t set)
    Get the CPU set of processors that are physically close to device idx.
    Definition: cudart.h:89
    -
    hwloc_cudart_get_device_osdev_by_index
    static hwloc_obj_t hwloc_cudart_get_device_osdev_by_index(hwloc_topology_t topology, unsigned idx)
    Get the hwloc OS device object corresponding to the CUDA device whose index is idx.
    Definition: cudart.h:156
    -
    hwloc_cudart_get_device_pci_ids
    static int hwloc_cudart_get_device_pci_ids(hwloc_topology_t topology, int idx, int *domain, int *bus, int *dev)
    Return the domain, bus and device IDs of the CUDA device whose index is idx.
    Definition: cudart.h:48
    -
    hwloc_cudart_get_device_pcidev
    static hwloc_obj_t hwloc_cudart_get_device_pcidev(hwloc_topology_t topology, int idx)
    Get the hwloc PCI device object corresponding to the CUDA device whose index is idx.
    Definition: cudart.h:128
    -
    hwloc_obj
    Structure of a topology object.
    Definition: hwloc.h:396
    -
    hwloc_obj::name
    char * name
    Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name str...
    Definition: hwloc.h:408
    -
    hwloc_obj::attr
    union hwloc_obj_attr_u * attr
    Object type-specific Attributes, may be NULL if no attribute value was found.
    Definition: hwloc.h:415
    -
    hwloc_obj_attr_u::osdev
    struct hwloc_obj_attr_u::hwloc_osdev_attr_s osdev
    -
    hwloc_obj_attr_u::hwloc_osdev_attr_s::type
    hwloc_obj_osdev_type_t type
    Definition: hwloc.h:666
    -
    - - - - - - - - -
    -
    -
    nvml.h
    -
    -
    -
    1 /*
    -
    2  * Copyright © 2012-2021 Inria. All rights reserved.
    -
    3  * See COPYING in top-level directory.
    -
    4  */
    -
    5 
    -
    13 #ifndef HWLOC_NVML_H
    -
    14 #define HWLOC_NVML_H
    -
    15 
    -
    16 #include "hwloc.h"
    -
    17 #include "hwloc/autogen/config.h"
    -
    18 #include "hwloc/helper.h"
    -
    19 #ifdef HWLOC_LINUX_SYS
    -
    20 #include "hwloc/linux.h"
    -
    21 #endif
    -
    22 
    -
    23 #include <nvml.h>
    -
    24 
    -
    25 
    -
    26 #ifdef __cplusplus
    -
    27 extern "C" {
    -
    28 #endif
    -
    29 
    -
    30 
    -
    55 static __hwloc_inline int
    -
    56 hwloc_nvml_get_device_cpuset(hwloc_topology_t topology __hwloc_attribute_unused,
    -
    57  nvmlDevice_t device, hwloc_cpuset_t set)
    -
    58 {
    -
    59 #ifdef HWLOC_LINUX_SYS
    -
    60  /* If we're on Linux, use the sysfs mechanism to get the local cpus */
    -
    61 #define HWLOC_NVML_DEVICE_SYSFS_PATH_MAX 128
    -
    62  char path[HWLOC_NVML_DEVICE_SYSFS_PATH_MAX];
    -
    63  nvmlReturn_t nvres;
    -
    64  nvmlPciInfo_t pci;
    -
    65 
    -
    66  if (!hwloc_topology_is_thissystem(topology)) {
    -
    67  errno = EINVAL;
    -
    68  return -1;
    -
    69  }
    -
    70 
    -
    71  nvres = nvmlDeviceGetPciInfo(device, &pci);
    -
    72  if (NVML_SUCCESS != nvres) {
    -
    73  errno = EINVAL;
    -
    74  return -1;
    -
    75  }
    -
    76 
    -
    77  sprintf(path, "/sys/bus/pci/devices/%04x:%02x:%02x.0/local_cpus", pci.domain, pci.bus, pci.device);
    -
    78  if (hwloc_linux_read_path_as_cpumask(path, set) < 0
    -
    79  || hwloc_bitmap_iszero(set))
    -
    80  hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
    -
    81 #else
    -
    82  /* Non-Linux systems simply get a full cpuset */
    -
    83  hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
    -
    84 #endif
    -
    85  return 0;
    -
    86 }
    -
    87 
    -
    101 static __hwloc_inline hwloc_obj_t
    -
    102 hwloc_nvml_get_device_osdev_by_index(hwloc_topology_t topology, unsigned idx)
    -
    103 {
    -
    104  hwloc_obj_t osdev = NULL;
    -
    105  while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
    -
    106  if (HWLOC_OBJ_OSDEV_GPU == osdev->attr->osdev.type
    -
    107  && osdev->name
    -
    108  && !strncmp("nvml", osdev->name, 4)
    -
    109  && atoi(osdev->name + 4) == (int) idx)
    -
    110  return osdev;
    -
    111  }
    -
    112  return NULL;
    -
    113 }
    -
    114 
    -
    128 static __hwloc_inline hwloc_obj_t
    -
    129 hwloc_nvml_get_device_osdev(hwloc_topology_t topology, nvmlDevice_t device)
    -
    130 {
    -
    131  hwloc_obj_t osdev;
    -
    132  nvmlReturn_t nvres;
    -
    133  nvmlPciInfo_t pci;
    -
    134  char uuid[64];
    -
    135 
    -
    136  if (!hwloc_topology_is_thissystem(topology)) {
    -
    137  errno = EINVAL;
    -
    138  return NULL;
    -
    139  }
    -
    140 
    -
    141  nvres = nvmlDeviceGetPciInfo(device, &pci);
    -
    142  if (NVML_SUCCESS != nvres)
    -
    143  return NULL;
    -
    144 
    -
    145  nvres = nvmlDeviceGetUUID(device, uuid, sizeof(uuid));
    -
    146  if (NVML_SUCCESS != nvres)
    -
    147  uuid[0] = '\0';
    -
    148 
    -
    149  osdev = NULL;
    -
    150  while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
    -
    151  hwloc_obj_t pcidev = osdev->parent;
    -
    152  const char *info;
    -
    153 
    -
    154  if (strncmp(osdev->name, "nvml", 4))
    -
    155  continue;
    -
    156 
    -
    157  if (pcidev
    -
    158  && pcidev->type == HWLOC_OBJ_PCI_DEVICE
    -
    159  && pcidev->attr->pcidev.domain == pci.domain
    -
    160  && pcidev->attr->pcidev.bus == pci.bus
    -
    161  && pcidev->attr->pcidev.dev == pci.device
    -
    162  && pcidev->attr->pcidev.func == 0)
    -
    163  return osdev;
    -
    164 
    -
    165  info = hwloc_obj_get_info_by_name(osdev, "NVIDIAUUID");
    -
    166  if (info && !strcmp(info, uuid))
    -
    167  return osdev;
    -
    168  }
    -
    169 
    -
    170  return NULL;
    -
    171 }
    -
    172 
    -
    176 #ifdef __cplusplus
    -
    177 } /* extern "C" */
    -
    178 #endif
    -
    179 
    -
    180 
    -
    181 #endif /* HWLOC_NVML_H */
    -
    hwloc_cpuset_t
    hwloc_bitmap_t hwloc_cpuset_t
    A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
    Definition: hwloc.h:140
    -
    HWLOC_OBJ_OSDEV_GPU
    @ HWLOC_OBJ_OSDEV_GPU
    Operating system GPU device. For instance ":0.0" for a GL display, "card0" for a Linux DRM device.
    Definition: hwloc.h:342
    -
    HWLOC_OBJ_PCI_DEVICE
    @ HWLOC_OBJ_PCI_DEVICE
    PCI device (filtered out by default).
    Definition: hwloc.h:269
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:692
    -
    hwloc_obj_get_info_by_name
    static const char * hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name)
    Search the given key name in object infos and return the corresponding value.
    -
    hwloc_topology_is_thissystem
    int hwloc_topology_is_thissystem(hwloc_topology_t restrict topology)
    Does the topology context come from this system?
    -
    hwloc_topology_get_complete_cpuset
    hwloc_const_cpuset_t hwloc_topology_get_complete_cpuset(hwloc_topology_t topology)
    Get complete CPU set.
    -
    hwloc_get_next_osdev
    static hwloc_obj_t hwloc_get_next_osdev(hwloc_topology_t topology, hwloc_obj_t prev)
    Get the next OS device in the system.
    Definition: helper.h:1191
    -
    hwloc_bitmap_iszero
    int hwloc_bitmap_iszero(hwloc_const_bitmap_t bitmap)
    Test whether bitmap bitmap is empty.
    -
    hwloc_bitmap_copy
    int hwloc_bitmap_copy(hwloc_bitmap_t dst, hwloc_const_bitmap_t src)
    Copy the contents of bitmap src into the already allocated bitmap dst.
    -
    hwloc_linux_read_path_as_cpumask
    int hwloc_linux_read_path_as_cpumask(const char *path, hwloc_bitmap_t set)
    Convert a linux kernel cpumask file path into a hwloc bitmap set.
    -
    hwloc_nvml_get_device_cpuset
    static int hwloc_nvml_get_device_cpuset(hwloc_topology_t topology, nvmlDevice_t device, hwloc_cpuset_t set)
    Get the CPU set of processors that are physically close to NVML device device.
    Definition: nvml.h:56
    -
    hwloc_nvml_get_device_osdev_by_index
    static hwloc_obj_t hwloc_nvml_get_device_osdev_by_index(hwloc_topology_t topology, unsigned idx)
    Get the hwloc OS device object corresponding to the NVML device whose index is idx.
    Definition: nvml.h:102
    -
    hwloc_nvml_get_device_osdev
    static hwloc_obj_t hwloc_nvml_get_device_osdev(hwloc_topology_t topology, nvmlDevice_t device)
    Get the hwloc OS device object corresponding to NVML device device.
    Definition: nvml.h:129
    -
    hwloc_obj
    Structure of a topology object.
    Definition: hwloc.h:396
    -
    hwloc_obj::name
    char * name
    Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name str...
    Definition: hwloc.h:408
    -
    hwloc_obj::type
    hwloc_obj_type_t type
    Type of object.
    Definition: hwloc.h:398
    -
    hwloc_obj::attr
    union hwloc_obj_attr_u * attr
    Object type-specific Attributes, may be NULL if no attribute value was found.
    Definition: hwloc.h:415
    -
    hwloc_obj::parent
    struct hwloc_obj * parent
    Parent, NULL if root (Machine object)
    Definition: hwloc.h:446
    -
    hwloc_obj_attr_u::pcidev
    struct hwloc_obj_attr_u::hwloc_pcidev_attr_s pcidev
    -
    hwloc_obj_attr_u::osdev
    struct hwloc_obj_attr_u::hwloc_osdev_attr_s osdev
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::dev
    unsigned char dev
    Definition: hwloc.h:639
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::func
    unsigned char func
    Definition: hwloc.h:639
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::domain
    unsigned short domain
    Definition: hwloc.h:635
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::bus
    unsigned char bus
    Definition: hwloc.h:639
    -
    hwloc_obj_attr_u::hwloc_osdev_attr_s::type
    hwloc_obj_osdev_type_t type
    Definition: hwloc.h:666
    -
    - - - - - - - - -
    -
    -
    rsmi.h
    -
    -
    -
    1 /*
    -
    2  * Copyright © 2012-2021 Inria. All rights reserved.
    -
    3  * Copyright (c) 2020, Advanced Micro Devices, Inc. All rights reserved.
    -
    4  * Written by Advanced Micro Devices,
    -
    5  * See COPYING in top-level directory.
    -
    6  */
    -
    7 
    -
    15 #ifndef HWLOC_RSMI_H
    -
    16 #define HWLOC_RSMI_H
    -
    17 
    -
    18 #include "hwloc.h"
    -
    19 #include "hwloc/autogen/config.h"
    -
    20 #include "hwloc/helper.h"
    -
    21 #ifdef HWLOC_LINUX_SYS
    -
    22 #include "hwloc/linux.h"
    -
    23 #endif
    -
    24 
    -
    25 #include <rocm_smi/rocm_smi.h>
    -
    26 
    -
    27 
    -
    28 #ifdef __cplusplus
    -
    29 extern "C" {
    -
    30 #endif
    -
    31 
    -
    32 
    -
    59 static __hwloc_inline int
    -
    60 hwloc_rsmi_get_device_cpuset(hwloc_topology_t topology __hwloc_attribute_unused,
    -
    61  uint32_t dv_ind, hwloc_cpuset_t set)
    -
    62 {
    -
    63 #ifdef HWLOC_LINUX_SYS
    -
    64  /* If we're on Linux, use the sysfs mechanism to get the local cpus */
    -
    65 #define HWLOC_RSMI_DEVICE_SYSFS_PATH_MAX 128
    -
    66  char path[HWLOC_RSMI_DEVICE_SYSFS_PATH_MAX];
    -
    67  rsmi_status_t ret;
    -
    68  uint64_t bdfid = 0;
    -
    69  unsigned domain, device, bus;
    -
    70 
    -
    71  if (!hwloc_topology_is_thissystem(topology)) {
    -
    72  errno = EINVAL;
    -
    73  return -1;
    -
    74  }
    -
    75 
    -
    76  ret = rsmi_dev_pci_id_get(dv_ind, &bdfid);
    -
    77  if (RSMI_STATUS_SUCCESS != ret) {
    -
    78  errno = EINVAL;
    -
    79  return -1;
    -
    80  }
    -
    81  domain = (bdfid>>32) & 0xffffffff;
    -
    82  bus = ((bdfid & 0xffff)>>8) & 0xff;
    -
    83  device = ((bdfid & 0xff)>>3) & 0x1f;
    -
    84 
    -
    85  sprintf(path, "/sys/bus/pci/devices/%04x:%02x:%02x.0/local_cpus", domain, bus, device);
    -
    86  if (hwloc_linux_read_path_as_cpumask(path, set) < 0
    -
    87  || hwloc_bitmap_iszero(set))
    -
    88  hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
    -
    89 #else
    -
    90  /* Non-Linux systems simply get a full cpuset */
    -
    91  hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
    -
    92 #endif
    -
    93  return 0;
    -
    94 }
    -
    95 
    -
    111 static __hwloc_inline hwloc_obj_t
    -
    112 hwloc_rsmi_get_device_osdev_by_index(hwloc_topology_t topology, uint32_t dv_ind)
    -
    113 {
    -
    114  hwloc_obj_t osdev = NULL;
    -
    115  while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
    -
    116  if (HWLOC_OBJ_OSDEV_GPU == osdev->attr->osdev.type
    -
    117  && osdev->name
    -
    118  && !strncmp("rsmi", osdev->name, 4)
    -
    119  && atoi(osdev->name + 4) == (int) dv_ind)
    -
    120  return osdev;
    -
    121  }
    -
    122  return NULL;
    -
    123 }
    -
    124 
    -
    140 static __hwloc_inline hwloc_obj_t
    -
    141 hwloc_rsmi_get_device_osdev(hwloc_topology_t topology, uint32_t dv_ind)
    -
    142 {
    -
    143  hwloc_obj_t osdev;
    -
    144  rsmi_status_t ret;
    -
    145  uint64_t bdfid = 0;
    -
    146  unsigned domain, device, bus, func;
    -
    147  uint64_t id;
    -
    148  char uuid[64];
    -
    149 
    -
    150  if (!hwloc_topology_is_thissystem(topology)) {
    -
    151  errno = EINVAL;
    -
    152  return NULL;
    -
    153  }
    -
    154 
    -
    155  ret = rsmi_dev_pci_id_get(dv_ind, &bdfid);
    -
    156  if (RSMI_STATUS_SUCCESS != ret) {
    -
    157  errno = EINVAL;
    -
    158  return NULL;
    -
    159  }
    -
    160  domain = (bdfid>>32) & 0xffffffff;
    -
    161  bus = ((bdfid & 0xffff)>>8) & 0xff;
    -
    162  device = ((bdfid & 0xff)>>3) & 0x1f;
    -
    163  func = bdfid & 0x7;
    -
    164 
    -
    165  ret = rsmi_dev_unique_id_get(dv_ind, &id);
    -
    166  if (RSMI_STATUS_SUCCESS != ret)
    -
    167  uuid[0] = '\0';
    -
    168  else
    -
    169  sprintf(uuid, "%lx", id);
    -
    170 
    -
    171  osdev = NULL;
    -
    172  while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
    -
    173  hwloc_obj_t pcidev = osdev->parent;
    -
    174  const char *info;
    -
    175 
    -
    176  if (strncmp(osdev->name, "rsmi", 4))
    -
    177  continue;
    -
    178 
    -
    179  if (pcidev
    -
    180  && pcidev->type == HWLOC_OBJ_PCI_DEVICE
    -
    181  && pcidev->attr->pcidev.domain == domain
    -
    182  && pcidev->attr->pcidev.bus == bus
    -
    183  && pcidev->attr->pcidev.dev == device
    -
    184  && pcidev->attr->pcidev.func == func)
    -
    185  return osdev;
    -
    186 
    -
    187  info = hwloc_obj_get_info_by_name(osdev, "AMDUUID");
    -
    188  if (info && !strcmp(info, uuid))
    -
    189  return osdev;
    -
    190  }
    -
    191 
    -
    192  return NULL;
    -
    193 }
    -
    194 
    -
    198 #ifdef __cplusplus
    -
    199 } /* extern "C" */
    -
    200 #endif
    -
    201 
    -
    202 
    -
    203 #endif /* HWLOC_RSMI_H */
    -
    hwloc_cpuset_t
    hwloc_bitmap_t hwloc_cpuset_t
    A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
    Definition: hwloc.h:140
    -
    HWLOC_OBJ_OSDEV_GPU
    @ HWLOC_OBJ_OSDEV_GPU
    Operating system GPU device. For instance ":0.0" for a GL display, "card0" for a Linux DRM device.
    Definition: hwloc.h:342
    -
    HWLOC_OBJ_PCI_DEVICE
    @ HWLOC_OBJ_PCI_DEVICE
    PCI device (filtered out by default).
    Definition: hwloc.h:269
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:692
    -
    hwloc_obj_get_info_by_name
    static const char * hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name)
    Search the given key name in object infos and return the corresponding value.
    -
    hwloc_topology_is_thissystem
    int hwloc_topology_is_thissystem(hwloc_topology_t restrict topology)
    Does the topology context come from this system?
    -
    hwloc_topology_get_complete_cpuset
    hwloc_const_cpuset_t hwloc_topology_get_complete_cpuset(hwloc_topology_t topology)
    Get complete CPU set.
    -
    hwloc_get_next_osdev
    static hwloc_obj_t hwloc_get_next_osdev(hwloc_topology_t topology, hwloc_obj_t prev)
    Get the next OS device in the system.
    Definition: helper.h:1191
    -
    hwloc_bitmap_iszero
    int hwloc_bitmap_iszero(hwloc_const_bitmap_t bitmap)
    Test whether bitmap bitmap is empty.
    -
    hwloc_bitmap_copy
    int hwloc_bitmap_copy(hwloc_bitmap_t dst, hwloc_const_bitmap_t src)
    Copy the contents of bitmap src into the already allocated bitmap dst.
    -
    hwloc_linux_read_path_as_cpumask
    int hwloc_linux_read_path_as_cpumask(const char *path, hwloc_bitmap_t set)
    Convert a linux kernel cpumask file path into a hwloc bitmap set.
    -
    hwloc_rsmi_get_device_osdev_by_index
    static hwloc_obj_t hwloc_rsmi_get_device_osdev_by_index(hwloc_topology_t topology, uint32_t dv_ind)
    Get the hwloc OS device object corresponding to the AMD GPU device whose index is dv_ind.
    Definition: rsmi.h:112
    -
    hwloc_rsmi_get_device_osdev
    static hwloc_obj_t hwloc_rsmi_get_device_osdev(hwloc_topology_t topology, uint32_t dv_ind)
    Get the hwloc OS device object corresponding to AMD GPU device, whose index is dv_ind.
    Definition: rsmi.h:141
    -
    hwloc_rsmi_get_device_cpuset
    static int hwloc_rsmi_get_device_cpuset(hwloc_topology_t topology, uint32_t dv_ind, hwloc_cpuset_t set)
    Get the CPU set of logical processors that are physically close to AMD GPU device whose index is dv_i...
    Definition: rsmi.h:60
    -
    hwloc_obj
    Structure of a topology object.
    Definition: hwloc.h:396
    -
    hwloc_obj::name
    char * name
    Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name str...
    Definition: hwloc.h:408
    -
    hwloc_obj::type
    hwloc_obj_type_t type
    Type of object.
    Definition: hwloc.h:398
    -
    hwloc_obj::attr
    union hwloc_obj_attr_u * attr
    Object type-specific Attributes, may be NULL if no attribute value was found.
    Definition: hwloc.h:415
    -
    hwloc_obj::parent
    struct hwloc_obj * parent
    Parent, NULL if root (Machine object)
    Definition: hwloc.h:446
    -
    hwloc_obj_attr_u::pcidev
    struct hwloc_obj_attr_u::hwloc_pcidev_attr_s pcidev
    -
    hwloc_obj_attr_u::osdev
    struct hwloc_obj_attr_u::hwloc_osdev_attr_s osdev
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::dev
    unsigned char dev
    Definition: hwloc.h:639
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::func
    unsigned char func
    Definition: hwloc.h:639
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::domain
    unsigned short domain
    Definition: hwloc.h:635
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::bus
    unsigned char bus
    Definition: hwloc.h:639
    -
    hwloc_obj_attr_u::hwloc_osdev_attr_s::type
    hwloc_obj_osdev_type_t type
    Definition: hwloc.h:666
    -
    - - - - - - - - -
    -
    -
    levelzero.h
    -
    -
    -
    1 /*
    -
    2  * Copyright © 2021 Inria. All rights reserved.
    -
    3  * See COPYING in top-level directory.
    -
    4  */
    -
    5 
    -
    13 #ifndef HWLOC_LEVELZERO_H
    -
    14 #define HWLOC_LEVELZERO_H
    -
    15 
    -
    16 #include "hwloc.h"
    -
    17 #include "hwloc/autogen/config.h"
    -
    18 #include "hwloc/helper.h"
    -
    19 #ifdef HWLOC_LINUX_SYS
    -
    20 #include "hwloc/linux.h"
    -
    21 #endif
    -
    22 
    -
    23 #include <level_zero/ze_api.h>
    -
    24 #include <level_zero/zes_api.h>
    -
    25 
    -
    26 
    -
    27 #ifdef __cplusplus
    -
    28 extern "C" {
    -
    29 #endif
    -
    30 
    -
    31 
    -
    59 static __hwloc_inline int
    -
    60 hwloc_levelzero_get_device_cpuset(hwloc_topology_t topology __hwloc_attribute_unused,
    -
    61  ze_device_handle_t device, hwloc_cpuset_t set)
    -
    62 {
    -
    63 #ifdef HWLOC_LINUX_SYS
    -
    64  /* If we're on Linux, use the sysfs mechanism to get the local cpus */
    -
    65 #define HWLOC_LEVELZERO_DEVICE_SYSFS_PATH_MAX 128
    -
    66  char path[HWLOC_LEVELZERO_DEVICE_SYSFS_PATH_MAX];
    -
    67  zes_pci_properties_t pci;
    -
    68  zes_device_handle_t sdevice = device;
    -
    69  ze_result_t res;
    -
    70 
    -
    71  if (!hwloc_topology_is_thissystem(topology)) {
    -
    72  errno = EINVAL;
    -
    73  return -1;
    -
    74  }
    -
    75 
    -
    76  res = zesDevicePciGetProperties(sdevice, &pci);
    -
    77  if (res != ZE_RESULT_SUCCESS) {
    -
    78  errno = EINVAL;
    -
    79  return -1;
    -
    80  }
    -
    81 
    -
    82  sprintf(path, "/sys/bus/pci/devices/%04x:%02x:%02x.%01x/local_cpus",
    -
    83  pci.address.domain, pci.address.bus, pci.address.device, pci.address.function);
    -
    84  if (hwloc_linux_read_path_as_cpumask(path, set) < 0
    -
    85  || hwloc_bitmap_iszero(set))
    -
    86  hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
    -
    87 #else
    -
    88  /* Non-Linux systems simply get a full cpuset */
    -
    89  hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
    -
    90 #endif
    -
    91  return 0;
    -
    92 }
    -
    93 
    -
    108 static __hwloc_inline hwloc_obj_t
    -
    109 hwloc_levelzero_get_device_osdev(hwloc_topology_t topology, ze_device_handle_t device)
    -
    110 {
    -
    111  zes_device_handle_t sdevice = device;
    -
    112  zes_pci_properties_t pci;
    -
    113  ze_result_t res;
    -
    114  hwloc_obj_t osdev;
    -
    115 
    -
    116  if (!hwloc_topology_is_thissystem(topology)) {
    -
    117  errno = EINVAL;
    -
    118  return NULL;
    -
    119  }
    -
    120 
    -
    121  res = zesDevicePciGetProperties(sdevice, &pci);
    -
    122  if (res != ZE_RESULT_SUCCESS) {
    -
    123  /* L0 was likely initialized without sysman, don't bother */
    -
    124  errno = EINVAL;
    -
    125  return NULL;
    -
    126  }
    -
    127 
    -
    128  osdev = NULL;
    -
    129  while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
    -
    130  hwloc_obj_t pcidev = osdev->parent;
    -
    131 
    -
    132  if (strncmp(osdev->name, "ze", 2))
    -
    133  continue;
    -
    134 
    -
    135  if (pcidev
    -
    136  && pcidev->type == HWLOC_OBJ_PCI_DEVICE
    -
    137  && pcidev->attr->pcidev.domain == pci.address.domain
    -
    138  && pcidev->attr->pcidev.bus == pci.address.bus
    -
    139  && pcidev->attr->pcidev.dev == pci.address.device
    -
    140  && pcidev->attr->pcidev.func == pci.address.function)
    -
    141  return osdev;
    -
    142 
    -
    143  /* FIXME: when we'll have serialnumber, try it in case PCI is filtered-out */
    -
    144  }
    -
    145 
    -
    146  return NULL;
    -
    147 }
    -
    148 
    -
    152 #ifdef __cplusplus
    -
    153 } /* extern "C" */
    -
    154 #endif
    -
    155 
    -
    156 
    -
    157 #endif /* HWLOC_LEVELZERO_H */
    -
    hwloc_cpuset_t
    hwloc_bitmap_t hwloc_cpuset_t
    A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
    Definition: hwloc.h:140
    -
    HWLOC_OBJ_PCI_DEVICE
    @ HWLOC_OBJ_PCI_DEVICE
    PCI device (filtered out by default).
    Definition: hwloc.h:269
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:692
    -
    hwloc_topology_is_thissystem
    int hwloc_topology_is_thissystem(hwloc_topology_t restrict topology)
    Does the topology context come from this system?
    -
    hwloc_topology_get_complete_cpuset
    hwloc_const_cpuset_t hwloc_topology_get_complete_cpuset(hwloc_topology_t topology)
    Get complete CPU set.
    -
    hwloc_get_next_osdev
    static hwloc_obj_t hwloc_get_next_osdev(hwloc_topology_t topology, hwloc_obj_t prev)
    Get the next OS device in the system.
    Definition: helper.h:1191
    -
    hwloc_bitmap_iszero
    int hwloc_bitmap_iszero(hwloc_const_bitmap_t bitmap)
    Test whether bitmap bitmap is empty.
    -
    hwloc_bitmap_copy
    int hwloc_bitmap_copy(hwloc_bitmap_t dst, hwloc_const_bitmap_t src)
    Copy the contents of bitmap src into the already allocated bitmap dst.
    -
    hwloc_linux_read_path_as_cpumask
    int hwloc_linux_read_path_as_cpumask(const char *path, hwloc_bitmap_t set)
    Convert a linux kernel cpumask file path into a hwloc bitmap set.
    -
    hwloc_levelzero_get_device_cpuset
    static int hwloc_levelzero_get_device_cpuset(hwloc_topology_t topology, ze_device_handle_t device, hwloc_cpuset_t set)
    Get the CPU set of logical processors that are physically close to the Level Zero device device.
    Definition: levelzero.h:60
    -
    hwloc_levelzero_get_device_osdev
    static hwloc_obj_t hwloc_levelzero_get_device_osdev(hwloc_topology_t topology, ze_device_handle_t device)
    Get the hwloc OS device object corresponding to Level Zero device device.
    Definition: levelzero.h:109
    -
    hwloc_obj
    Structure of a topology object.
    Definition: hwloc.h:396
    -
    hwloc_obj::name
    char * name
    Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name str...
    Definition: hwloc.h:408
    -
    hwloc_obj::type
    hwloc_obj_type_t type
    Type of object.
    Definition: hwloc.h:398
    -
    hwloc_obj::attr
    union hwloc_obj_attr_u * attr
    Object type-specific Attributes, may be NULL if no attribute value was found.
    Definition: hwloc.h:415
    -
    hwloc_obj::parent
    struct hwloc_obj * parent
    Parent, NULL if root (Machine object)
    Definition: hwloc.h:446
    -
    hwloc_obj_attr_u::pcidev
    struct hwloc_obj_attr_u::hwloc_pcidev_attr_s pcidev
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::dev
    unsigned char dev
    Definition: hwloc.h:639
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::func
    unsigned char func
    Definition: hwloc.h:639
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::domain
    unsigned short domain
    Definition: hwloc.h:635
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::bus
    unsigned char bus
    Definition: hwloc.h:639
    -
    - - - - - - - - -
    -
    -
    gl.h
    -
    -
    -
    1 /*
    -
    2  * Copyright © 2012 Blue Brain Project, EPFL. All rights reserved.
    -
    3  * Copyright © 2012-2021 Inria. All rights reserved.
    -
    4  * See COPYING in top-level directory.
    -
    5  */
    -
    6 
    -
    14 #ifndef HWLOC_GL_H
    -
    15 #define HWLOC_GL_H
    -
    16 
    -
    17 #include "hwloc.h"
    -
    18 
    -
    19 #include <stdio.h>
    -
    20 #include <string.h>
    -
    21 
    -
    22 
    -
    23 #ifdef __cplusplus
    -
    24 extern "C" {
    -
    25 #endif
    -
    26 
    -
    27 
    -
    53 static __hwloc_inline hwloc_obj_t
    -
    54 hwloc_gl_get_display_osdev_by_port_device(hwloc_topology_t topology,
    -
    55  unsigned port, unsigned device)
    -
    56 {
    -
    57  unsigned x = (unsigned) -1, y = (unsigned) -1;
    -
    58  hwloc_obj_t osdev = NULL;
    -
    59  while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
    -
    60  if (HWLOC_OBJ_OSDEV_GPU == osdev->attr->osdev.type
    -
    61  && osdev->name
    -
    62  && sscanf(osdev->name, ":%u.%u", &x, &y) == 2
    -
    63  && port == x && device == y)
    -
    64  return osdev;
    -
    65  }
    -
    66  errno = EINVAL;
    -
    67  return NULL;
    -
    68 }
    -
    69 
    -
    84 static __hwloc_inline hwloc_obj_t
    -
    85 hwloc_gl_get_display_osdev_by_name(hwloc_topology_t topology,
    -
    86  const char *name)
    -
    87 {
    -
    88  hwloc_obj_t osdev = NULL;
    -
    89  while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
    -
    90  if (HWLOC_OBJ_OSDEV_GPU == osdev->attr->osdev.type
    -
    91  && osdev->name
    -
    92  && !strcmp(name, osdev->name))
    -
    93  return osdev;
    -
    94  }
    -
    95  errno = EINVAL;
    -
    96  return NULL;
    -
    97 }
    -
    98 
    -
    111 static __hwloc_inline int
    -
    112 hwloc_gl_get_display_by_osdev(hwloc_topology_t topology __hwloc_attribute_unused,
    -
    113  hwloc_obj_t osdev,
    -
    114  unsigned *port, unsigned *device)
    -
    115 {
    -
    116  unsigned x = -1, y = -1;
    -
    117  if (HWLOC_OBJ_OSDEV_GPU == osdev->attr->osdev.type
    -
    118  && sscanf(osdev->name, ":%u.%u", &x, &y) == 2) {
    -
    119  *port = x;
    -
    120  *device = y;
    -
    121  return 0;
    -
    122  }
    -
    123  errno = EINVAL;
    -
    124  return -1;
    -
    125 }
    -
    126 
    -
    130 #ifdef __cplusplus
    -
    131 } /* extern "C" */
    -
    132 #endif
    -
    133 
    -
    134 
    -
    135 #endif /* HWLOC_GL_H */
    -
    136 
    -
    HWLOC_OBJ_OSDEV_GPU
    @ HWLOC_OBJ_OSDEV_GPU
    Operating system GPU device. For instance ":0.0" for a GL display, "card0" for a Linux DRM device.
    Definition: hwloc.h:342
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:692
    -
    hwloc_get_next_osdev
    static hwloc_obj_t hwloc_get_next_osdev(hwloc_topology_t topology, hwloc_obj_t prev)
    Get the next OS device in the system.
    Definition: helper.h:1191
    -
    hwloc_gl_get_display_osdev_by_name
    static hwloc_obj_t hwloc_gl_get_display_osdev_by_name(hwloc_topology_t topology, const char *name)
    Get the hwloc OS device object corresponding to the OpenGL display given by name.
    Definition: gl.h:85
    -
    hwloc_gl_get_display_osdev_by_port_device
    static hwloc_obj_t hwloc_gl_get_display_osdev_by_port_device(hwloc_topology_t topology, unsigned port, unsigned device)
    Get the hwloc OS device object corresponding to the OpenGL display given by port and device index.
    Definition: gl.h:54
    -
    hwloc_gl_get_display_by_osdev
    static int hwloc_gl_get_display_by_osdev(hwloc_topology_t topology, hwloc_obj_t osdev, unsigned *port, unsigned *device)
    Get the OpenGL display port and device corresponding to the given hwloc OS object.
    Definition: gl.h:112
    -
    hwloc_obj
    Structure of a topology object.
    Definition: hwloc.h:396
    -
    hwloc_obj::name
    char * name
    Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name str...
    Definition: hwloc.h:408
    -
    hwloc_obj::attr
    union hwloc_obj_attr_u * attr
    Object type-specific Attributes, may be NULL if no attribute value was found.
    Definition: hwloc.h:415
    -
    hwloc_obj_attr_u::osdev
    struct hwloc_obj_attr_u::hwloc_osdev_attr_s osdev
    -
    hwloc_obj_attr_u::hwloc_osdev_attr_s::type
    hwloc_obj_osdev_type_t type
    Definition: hwloc.h:666
    -
    - - - - - - - - -
    -
    -
    openfabrics-verbs.h
    -
    -
    -
    1 /*
    -
    2  * Copyright © 2009 CNRS
    -
    3  * Copyright © 2009-2021 Inria. All rights reserved.
    -
    4  * Copyright © 2009-2010 Université Bordeaux
    -
    5  * Copyright © 2009-2011 Cisco Systems, Inc. All rights reserved.
    -
    6  * See COPYING in top-level directory.
    -
    7  */
    -
    8 
    -
    19 #ifndef HWLOC_OPENFABRICS_VERBS_H
    -
    20 #define HWLOC_OPENFABRICS_VERBS_H
    -
    21 
    -
    22 #include "hwloc.h"
    -
    23 #include "hwloc/autogen/config.h"
    -
    24 #ifdef HWLOC_LINUX_SYS
    -
    25 #include "hwloc/linux.h"
    -
    26 #endif
    -
    27 
    -
    28 #include <infiniband/verbs.h>
    -
    29 
    -
    30 
    -
    31 #ifdef __cplusplus
    -
    32 extern "C" {
    -
    33 #endif
    -
    34 
    -
    35 
    -
    61 static __hwloc_inline int
    -
    62 hwloc_ibv_get_device_cpuset(hwloc_topology_t topology __hwloc_attribute_unused,
    -
    63  struct ibv_device *ibdev, hwloc_cpuset_t set)
    -
    64 {
    -
    65 #ifdef HWLOC_LINUX_SYS
    -
    66  /* If we're on Linux, use the verbs-provided sysfs mechanism to
    -
    67  get the local cpus */
    -
    68 #define HWLOC_OPENFABRICS_VERBS_SYSFS_PATH_MAX 128
    -
    69  char path[HWLOC_OPENFABRICS_VERBS_SYSFS_PATH_MAX];
    -
    70 
    -
    71  if (!hwloc_topology_is_thissystem(topology)) {
    -
    72  errno = EINVAL;
    -
    73  return -1;
    -
    74  }
    -
    75 
    -
    76  sprintf(path, "/sys/class/infiniband/%s/device/local_cpus",
    -
    77  ibv_get_device_name(ibdev));
    -
    78  if (hwloc_linux_read_path_as_cpumask(path, set) < 0
    -
    79  || hwloc_bitmap_iszero(set))
    -
    80  hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
    -
    81 #else
    -
    82  /* Non-Linux systems simply get a full cpuset */
    -
    83  hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
    -
    84 #endif
    -
    85  return 0;
    -
    86 }
    -
    87 
    -
    105 static __hwloc_inline hwloc_obj_t
    -
    106 hwloc_ibv_get_device_osdev_by_name(hwloc_topology_t topology,
    -
    107  const char *ibname)
    -
    108 {
    -
    109  hwloc_obj_t osdev = NULL;
    -
    110  while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
    -
    111  if (HWLOC_OBJ_OSDEV_OPENFABRICS == osdev->attr->osdev.type
    -
    112  && osdev->name && !strcmp(ibname, osdev->name))
    -
    113  return osdev;
    -
    114  }
    -
    115  return NULL;
    -
    116 }
    -
    117 
    -
    133 static __hwloc_inline hwloc_obj_t
    -
    134 hwloc_ibv_get_device_osdev(hwloc_topology_t topology,
    -
    135  struct ibv_device *ibdev)
    -
    136 {
    -
    137  if (!hwloc_topology_is_thissystem(topology)) {
    -
    138  errno = EINVAL;
    -
    139  return NULL;
    -
    140  }
    -
    141  return hwloc_ibv_get_device_osdev_by_name(topology, ibv_get_device_name(ibdev));
    -
    142 }
    -
    143 
    -
    147 #ifdef __cplusplus
    -
    148 } /* extern "C" */
    -
    149 #endif
    -
    150 
    -
    151 
    -
    152 #endif /* HWLOC_OPENFABRICS_VERBS_H */
    -
    hwloc_cpuset_t
    hwloc_bitmap_t hwloc_cpuset_t
    A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
    Definition: hwloc.h:140
    -
    HWLOC_OBJ_OSDEV_OPENFABRICS
    @ HWLOC_OBJ_OSDEV_OPENFABRICS
    Operating system openfabrics device. For instance the "mlx4_0" InfiniBand HCA, "hfi1_0" Omni-Path int...
    Definition: hwloc.h:347
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:692
    -
    hwloc_topology_is_thissystem
    int hwloc_topology_is_thissystem(hwloc_topology_t restrict topology)
    Does the topology context come from this system?
    -
    hwloc_topology_get_complete_cpuset
    hwloc_const_cpuset_t hwloc_topology_get_complete_cpuset(hwloc_topology_t topology)
    Get complete CPU set.
    -
    hwloc_get_next_osdev
    static hwloc_obj_t hwloc_get_next_osdev(hwloc_topology_t topology, hwloc_obj_t prev)
    Get the next OS device in the system.
    Definition: helper.h:1191
    -
    hwloc_bitmap_iszero
    int hwloc_bitmap_iszero(hwloc_const_bitmap_t bitmap)
    Test whether bitmap bitmap is empty.
    -
    hwloc_bitmap_copy
    int hwloc_bitmap_copy(hwloc_bitmap_t dst, hwloc_const_bitmap_t src)
    Copy the contents of bitmap src into the already allocated bitmap dst.
    -
    hwloc_linux_read_path_as_cpumask
    int hwloc_linux_read_path_as_cpumask(const char *path, hwloc_bitmap_t set)
    Convert a linux kernel cpumask file path into a hwloc bitmap set.
    -
    hwloc_ibv_get_device_osdev_by_name
    static hwloc_obj_t hwloc_ibv_get_device_osdev_by_name(hwloc_topology_t topology, const char *ibname)
    Get the hwloc OS device object corresponding to the OpenFabrics device named ibname.
    Definition: openfabrics-verbs.h:106
    -
    hwloc_ibv_get_device_cpuset
    static int hwloc_ibv_get_device_cpuset(hwloc_topology_t topology, struct ibv_device *ibdev, hwloc_cpuset_t set)
    Get the CPU set of processors that are physically close to device ibdev.
    Definition: openfabrics-verbs.h:62
    -
    hwloc_ibv_get_device_osdev
    static hwloc_obj_t hwloc_ibv_get_device_osdev(hwloc_topology_t topology, struct ibv_device *ibdev)
    Get the hwloc OS device object corresponding to the OpenFabrics device ibdev.
    Definition: openfabrics-verbs.h:134
    -
    hwloc_obj
    Structure of a topology object.
    Definition: hwloc.h:396
    -
    hwloc_obj::name
    char * name
    Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name str...
    Definition: hwloc.h:408
    -
    hwloc_obj::attr
    union hwloc_obj_attr_u * attr
    Object type-specific Attributes, may be NULL if no attribute value was found.
    Definition: hwloc.h:415
    -
    hwloc_obj_attr_u::osdev
    struct hwloc_obj_attr_u::hwloc_osdev_attr_s osdev
    -
    hwloc_obj_attr_u::hwloc_osdev_attr_s::type
    hwloc_obj_osdev_type_t type
    Definition: hwloc.h:666
    -
    - - - - - - - - -
    -
    -
    diff.h
    -
    -
    -
    1 /*
    -
    2  * Copyright © 2013-2020 Inria. All rights reserved.
    -
    3  * See COPYING in top-level directory.
    -
    4  */
    -
    5 
    -
    10 #ifndef HWLOC_DIFF_H
    -
    11 #define HWLOC_DIFF_H
    -
    12 
    -
    13 #ifndef HWLOC_H
    -
    14 #error Please include the main hwloc.h instead
    -
    15 #endif
    -
    16 
    -
    17 
    -
    18 #ifdef __cplusplus
    -
    19 extern "C" {
    -
    20 #elif 0
    -
    21 }
    -
    22 #endif
    -
    23 
    -
    24 
    -
    62 typedef enum hwloc_topology_diff_obj_attr_type_e {
    -
    67  HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_SIZE,
    -
    68 
    -
    74  HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_NAME,
    -
    78  HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_INFO
    -
    79 } hwloc_topology_diff_obj_attr_type_t;
    -
    80 
    -
    83 union hwloc_topology_diff_obj_attr_u {
    -
    84  struct hwloc_topology_diff_obj_attr_generic_s {
    -
    85  /* each part of the union must start with these */
    -
    86  hwloc_topology_diff_obj_attr_type_t type;
    -
    87  } generic;
    -
    88 
    -
    90  struct hwloc_topology_diff_obj_attr_uint64_s {
    -
    91  /* used for storing integer attributes */
    -
    92  hwloc_topology_diff_obj_attr_type_t type;
    -
    93  hwloc_uint64_t index; /* not used for SIZE */
    -
    94  hwloc_uint64_t oldvalue;
    -
    95  hwloc_uint64_t newvalue;
    -
    96  } uint64;
    -
    97 
    -
    99  struct hwloc_topology_diff_obj_attr_string_s {
    -
    100  /* used for storing name and info pairs */
    -
    101  hwloc_topology_diff_obj_attr_type_t type;
    -
    102  char *name; /* not used for NAME */
    -
    103  char *oldvalue;
    -
    104  char *newvalue;
    -
    105  } string;
    -
    106 };
    -
    107 
    -
    108 
    -
    111 typedef enum hwloc_topology_diff_type_e {
    -
    115  HWLOC_TOPOLOGY_DIFF_OBJ_ATTR,
    -
    116 
    -
    124  HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX
    -
    125 } hwloc_topology_diff_type_t;
    -
    126 
    -
    129 typedef union hwloc_topology_diff_u {
    -
    130  struct hwloc_topology_diff_generic_s {
    -
    131  /* each part of the union must start with these */
    -
    132  hwloc_topology_diff_type_t type;
    -
    133  union hwloc_topology_diff_u * next; /* pointer to the next element of the list, or NULL */
    -
    134  } generic;
    -
    135 
    -
    136  /* A difference in an object attribute. */
    -
    137  struct hwloc_topology_diff_obj_attr_s {
    -
    138  hwloc_topology_diff_type_t type; /* must be ::HWLOC_TOPOLOGY_DIFF_OBJ_ATTR */
    -
    139  union hwloc_topology_diff_u * next;
    -
    140  /* List of attribute differences for a single object */
    -
    141  int obj_depth;
    -
    142  unsigned obj_index;
    -
    143  union hwloc_topology_diff_obj_attr_u diff;
    -
    144  } obj_attr;
    -
    145 
    -
    146  /* A difference that is too complex. */
    -
    147  struct hwloc_topology_diff_too_complex_s {
    -
    148  hwloc_topology_diff_type_t type; /* must be ::HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX */
    -
    149  union hwloc_topology_diff_u * next;
    -
    150  /* Where we had to stop computing the diff in the first topology */
    -
    151  int obj_depth;
    -
    152  unsigned obj_index;
    -
    153  } too_complex;
    -
    154 } * hwloc_topology_diff_t;
    -
    155 
    -
    156 
    -
    194 HWLOC_DECLSPEC int hwloc_topology_diff_build(hwloc_topology_t topology, hwloc_topology_t newtopology, unsigned long flags, hwloc_topology_diff_t *diff);
    -
    195 
    -
    198 enum hwloc_topology_diff_apply_flags_e {
    -
    202  HWLOC_TOPOLOGY_DIFF_APPLY_REVERSE = (1UL<<0)
    -
    203 };
    -
    204 
    -
    222 HWLOC_DECLSPEC int hwloc_topology_diff_apply(hwloc_topology_t topology, hwloc_topology_diff_t diff, unsigned long flags);
    -
    223 
    -
    226 HWLOC_DECLSPEC int hwloc_topology_diff_destroy(hwloc_topology_diff_t diff);
    -
    227 
    -
    239 HWLOC_DECLSPEC int hwloc_topology_diff_load_xml(const char *xmlpath, hwloc_topology_diff_t *diff, char **refname);
    -
    240 
    -
    250 HWLOC_DECLSPEC int hwloc_topology_diff_export_xml(hwloc_topology_diff_t diff, const char *refname, const char *xmlpath);
    -
    251 
    -
    263 HWLOC_DECLSPEC int hwloc_topology_diff_load_xmlbuffer(const char *xmlbuffer, int buflen, hwloc_topology_diff_t *diff, char **refname);
    -
    264 
    -
    279 HWLOC_DECLSPEC int hwloc_topology_diff_export_xmlbuffer(hwloc_topology_diff_t diff, const char *refname, char **xmlbuffer, int *buflen);
    -
    280 
    -
    284 #ifdef __cplusplus
    -
    285 } /* extern "C" */
    -
    286 #endif
    -
    287 
    -
    288 
    -
    289 #endif /* HWLOC_DIFF_H */
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:692
    -
    hwloc_topology_diff_t
    union hwloc_topology_diff_u * hwloc_topology_diff_t
    One element of a difference list between two topologies.
    -
    hwloc_topology_diff_load_xml
    int hwloc_topology_diff_load_xml(const char *xmlpath, hwloc_topology_diff_t *diff, char **refname)
    Load a list of topology differences from a XML file.
    -
    hwloc_topology_diff_type_e
    hwloc_topology_diff_type_e
    Type of one element of a difference list.
    Definition: diff.h:111
    -
    hwloc_topology_diff_destroy
    int hwloc_topology_diff_destroy(hwloc_topology_diff_t diff)
    Destroy a list of topology differences.
    -
    hwloc_topology_diff_obj_attr_type_t
    enum hwloc_topology_diff_obj_attr_type_e hwloc_topology_diff_obj_attr_type_t
    Type of one object attribute difference.
    -
    hwloc_topology_diff_type_t
    enum hwloc_topology_diff_type_e hwloc_topology_diff_type_t
    Type of one element of a difference list.
    -
    hwloc_topology_diff_obj_attr_type_e
    hwloc_topology_diff_obj_attr_type_e
    Type of one object attribute difference.
    Definition: diff.h:62
    -
    hwloc_topology_diff_export_xml
    int hwloc_topology_diff_export_xml(hwloc_topology_diff_t diff, const char *refname, const char *xmlpath)
    Export a list of topology differences to a XML file.
    -
    hwloc_topology_diff_build
    int hwloc_topology_diff_build(hwloc_topology_t topology, hwloc_topology_t newtopology, unsigned long flags, hwloc_topology_diff_t *diff)
    Compute the difference between 2 topologies.
    -
    hwloc_topology_diff_export_xmlbuffer
    int hwloc_topology_diff_export_xmlbuffer(hwloc_topology_diff_t diff, const char *refname, char **xmlbuffer, int *buflen)
    Export a list of topology differences to a XML buffer.
    -
    hwloc_topology_diff_load_xmlbuffer
    int hwloc_topology_diff_load_xmlbuffer(const char *xmlbuffer, int buflen, hwloc_topology_diff_t *diff, char **refname)
    Load a list of topology differences from a XML buffer.
    -
    hwloc_topology_diff_apply_flags_e
    hwloc_topology_diff_apply_flags_e
    Flags to be given to hwloc_topology_diff_apply().
    Definition: diff.h:198
    -
    hwloc_topology_diff_apply
    int hwloc_topology_diff_apply(hwloc_topology_t topology, hwloc_topology_diff_t diff, unsigned long flags)
    Apply a topology diff to an existing topology.
    -
    HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX
    @ HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX
    The difference is too complex, it cannot be represented. The difference below this object has not bee...
    Definition: diff.h:124
    -
    HWLOC_TOPOLOGY_DIFF_OBJ_ATTR
    @ HWLOC_TOPOLOGY_DIFF_OBJ_ATTR
    An object attribute was changed. The union is a hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s...
    Definition: diff.h:115
    -
    HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_INFO
    @ HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_INFO
    the value of an info attribute is modified. The union is a hwloc_topology_diff_obj_attr_u::hwloc_topo...
    Definition: diff.h:78
    -
    HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_NAME
    @ HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_NAME
    The object name is modified. The union is a hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_a...
    Definition: diff.h:74
    -
    HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_SIZE
    @ HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_SIZE
    The object local memory is modified. The union is a hwloc_topology_diff_obj_attr_u::hwloc_topology_di...
    Definition: diff.h:67
    -
    HWLOC_TOPOLOGY_DIFF_APPLY_REVERSE
    @ HWLOC_TOPOLOGY_DIFF_APPLY_REVERSE
    Apply topology diff in reverse direction.
    Definition: diff.h:202
    -
    hwloc_topology_diff_obj_attr_u
    One object attribute difference.
    Definition: diff.h:83
    -
    hwloc_topology_diff_obj_attr_u::string
    struct hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s string
    -
    hwloc_topology_diff_obj_attr_u::uint64
    struct hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s uint64
    - -
    hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_generic_s::type
    hwloc_topology_diff_obj_attr_type_t type
    Definition: diff.h:86
    -
    hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s
    Integer attribute modification with an optional index.
    Definition: diff.h:90
    - - - -
    hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s::type
    hwloc_topology_diff_obj_attr_type_t type
    Definition: diff.h:92
    -
    hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s
    String attribute modification with an optional name.
    Definition: diff.h:99
    - - -
    hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s::type
    hwloc_topology_diff_obj_attr_type_t type
    Definition: diff.h:101
    - -
    hwloc_topology_diff_u
    One element of a difference list between two topologies.
    Definition: diff.h:129
    - -
    hwloc_topology_diff_u::hwloc_topology_diff_generic_s::type
    hwloc_topology_diff_type_t type
    Definition: diff.h:132
    -
    hwloc_topology_diff_u::hwloc_topology_diff_generic_s::next
    union hwloc_topology_diff_u * next
    Definition: diff.h:133
    - -
    hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s::type
    hwloc_topology_diff_type_t type
    Definition: diff.h:138
    - -
    hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s::next
    union hwloc_topology_diff_u * next
    Definition: diff.h:139
    - -
    hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s::next
    union hwloc_topology_diff_u * next
    Definition: diff.h:149
    - -
    hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s::type
    hwloc_topology_diff_type_t type
    Definition: diff.h:148
    - -
    - - - - - - - - -
    -
    -
    shmem.h
    -
    -
    -
    1 /*
    -
    2  * Copyright © 2013-2018 Inria. All rights reserved.
    -
    3  * See COPYING in top-level directory.
    -
    4  */
    -
    5 
    -
    10 #ifndef HWLOC_SHMEM_H
    -
    11 #define HWLOC_SHMEM_H
    -
    12 
    -
    13 #include "hwloc.h"
    -
    14 
    -
    15 #ifdef __cplusplus
    -
    16 extern "C" {
    -
    17 #elif 0
    -
    18 }
    -
    19 #endif
    -
    20 
    -
    21 
    -
    53 HWLOC_DECLSPEC int hwloc_shmem_topology_get_length(hwloc_topology_t topology,
    -
    54  size_t *lengthp,
    -
    55  unsigned long flags);
    -
    56 
    -
    82 HWLOC_DECLSPEC int hwloc_shmem_topology_write(hwloc_topology_t topology,
    -
    83  int fd, hwloc_uint64_t fileoffset,
    -
    84  void *mmap_address, size_t length,
    -
    85  unsigned long flags);
    -
    86 
    -
    125 HWLOC_DECLSPEC int hwloc_shmem_topology_adopt(hwloc_topology_t *topologyp,
    -
    126  int fd, hwloc_uint64_t fileoffset,
    -
    127  void *mmap_address, size_t length,
    -
    128  unsigned long flags);
    -
    132 #ifdef __cplusplus
    -
    133 } /* extern "C" */
    -
    134 #endif
    -
    135 
    -
    136 
    -
    137 #endif /* HWLOC_SHMEM_H */
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:692
    -
    hwloc_shmem_topology_adopt
    int hwloc_shmem_topology_adopt(hwloc_topology_t *topologyp, int fd, hwloc_uint64_t fileoffset, void *mmap_address, size_t length, unsigned long flags)
    Adopt a shared memory topology stored in a file.
    -
    hwloc_shmem_topology_write
    int hwloc_shmem_topology_write(hwloc_topology_t topology, int fd, hwloc_uint64_t fileoffset, void *mmap_address, size_t length, unsigned long flags)
    Duplicate a topology to a shared memory file.
    -
    hwloc_shmem_topology_get_length
    int hwloc_shmem_topology_get_length(hwloc_topology_t topology, size_t *lengthp, unsigned long flags)
    Get the required shared memory length for storing a topology.
    -
    - - - - - - - - -
    -
    -
    plugins.h
    -
    -
    -
    1 /*
    -
    2  * Copyright © 2013-2022 Inria. All rights reserved.
    -
    3  * Copyright © 2016 Cisco Systems, Inc. All rights reserved.
    -
    4  * See COPYING in top-level directory.
    -
    5  */
    -
    6 
    -
    7 #ifndef HWLOC_PLUGINS_H
    -
    8 #define HWLOC_PLUGINS_H
    -
    9 
    -
    14 struct hwloc_backend;
    -
    15 
    -
    16 #include "hwloc.h"
    -
    17 
    -
    18 #ifdef HWLOC_INSIDE_PLUGIN
    -
    19 /* needed for hwloc_plugin_check_namespace() */
    -
    20 #ifdef HWLOC_HAVE_LTDL
    -
    21 #include <ltdl.h>
    -
    22 #else
    -
    23 #include <dlfcn.h>
    -
    24 #endif
    -
    25 #endif
    -
    26 
    -
    27 
    -
    28 
    -
    41 struct hwloc_disc_component {
    -
    45  const char *name;
    -
    46 
    -
    50  unsigned phases;
    -
    51 
    -
    60  unsigned excluded_phases;
    -
    61 
    -
    65  struct hwloc_backend * (*instantiate)(struct hwloc_topology *topology, struct hwloc_disc_component *component, unsigned excluded_phases, const void *data1, const void *data2, const void *data3);
    -
    66 
    -
    79  unsigned priority;
    -
    80 
    -
    84  unsigned enabled_by_default;
    -
    85 
    -
    90  struct hwloc_disc_component * next;
    -
    91 };
    -
    92 
    -
    106 typedef enum hwloc_disc_phase_e {
    -
    111  HWLOC_DISC_PHASE_GLOBAL = (1U<<0),
    -
    112 
    -
    115  HWLOC_DISC_PHASE_CPU = (1U<<1),
    -
    116 
    -
    119  HWLOC_DISC_PHASE_MEMORY = (1U<<2),
    -
    120 
    -
    123  HWLOC_DISC_PHASE_PCI = (1U<<3),
    -
    124 
    -
    127  HWLOC_DISC_PHASE_IO = (1U<<4),
    -
    128 
    -
    131  HWLOC_DISC_PHASE_MISC = (1U<<5),
    -
    132 
    -
    135  HWLOC_DISC_PHASE_ANNOTATE = (1U<<6),
    -
    136 
    -
    142  HWLOC_DISC_PHASE_TWEAK = (1U<<7)
    -
    143 } hwloc_disc_phase_t;
    -
    144 
    -
    146 enum hwloc_disc_status_flag_e {
    -
    148  HWLOC_DISC_STATUS_FLAG_GOT_ALLOWED_RESOURCES = (1UL<<1)
    -
    149 };
    -
    150 
    -
    156 struct hwloc_disc_status {
    -
    160  hwloc_disc_phase_t phase;
    -
    161 
    -
    165  unsigned excluded_phases;
    -
    166 
    -
    168  unsigned long flags;
    -
    169 };
    -
    170 
    -
    189 struct hwloc_backend {
    -
    191  struct hwloc_disc_component * component;
    -
    193  struct hwloc_topology * topology;
    -
    195  int envvar_forced;
    -
    197  struct hwloc_backend * next;
    -
    198 
    -
    202  unsigned phases;
    -
    203 
    -
    205  unsigned long flags;
    -
    206 
    -
    213  int is_thissystem;
    -
    214 
    -
    216  void * private_data;
    -
    220  void (*disable)(struct hwloc_backend *backend);
    -
    221 
    -
    227  int (*discover)(struct hwloc_backend *backend, struct hwloc_disc_status *status);
    -
    228 
    -
    233  int (*get_pci_busid_cpuset)(struct hwloc_backend *backend, struct hwloc_pcidev_attr_s *busid, hwloc_bitmap_t cpuset);
    -
    234 };
    -
    235 
    -
    239 HWLOC_DECLSPEC struct hwloc_backend * hwloc_backend_alloc(struct hwloc_topology *topology, struct hwloc_disc_component *component);
    -
    240 
    -
    242 HWLOC_DECLSPEC int hwloc_backend_enable(struct hwloc_backend *backend);
    -
    243 
    -
    257 typedef enum hwloc_component_type_e {
    -
    259  HWLOC_COMPONENT_TYPE_DISC,
    -
    260 
    -
    262  HWLOC_COMPONENT_TYPE_XML
    -
    263 } hwloc_component_type_t;
    -
    264 
    -
    270 struct hwloc_component {
    -
    272  unsigned abi;
    -
    273 
    -
    291  int (*init)(unsigned long flags);
    -
    292 
    -
    304  void (*finalize)(unsigned long flags);
    -
    305 
    -
    307  hwloc_component_type_t type;
    -
    308 
    -
    310  unsigned long flags;
    -
    311 
    -
    313  void * data;
    -
    314 };
    -
    315 
    -
    345 HWLOC_DECLSPEC int hwloc_hide_errors(void);
    -
    346 
    -
    347 #define HWLOC_SHOW_CRITICAL_ERRORS() (hwloc_hide_errors() < 2)
    -
    348 #define HWLOC_SHOW_ALL_ERRORS() (hwloc_hide_errors() == 0)
    -
    349 
    -
    378 HWLOC_DECLSPEC hwloc_obj_t
    -
    379 hwloc__insert_object_by_cpuset(struct hwloc_topology *topology, hwloc_obj_t root,
    -
    380  hwloc_obj_t obj, const char *reason);
    -
    381 
    -
    398 HWLOC_DECLSPEC void hwloc_insert_object_by_parent(struct hwloc_topology *topology, hwloc_obj_t parent, hwloc_obj_t obj);
    -
    399 
    -
    404 HWLOC_DECLSPEC hwloc_obj_t hwloc_alloc_setup_object(hwloc_topology_t topology, hwloc_obj_type_t type, unsigned os_index);
    -
    405 
    -
    414 HWLOC_DECLSPEC int hwloc_obj_add_children_sets(hwloc_obj_t obj);
    -
    415 
    -
    423 HWLOC_DECLSPEC int hwloc_topology_reconnect(hwloc_topology_t topology, unsigned long flags __hwloc_attribute_unused);
    -
    424 
    -
    446 static __hwloc_inline int
    -
    447 hwloc_plugin_check_namespace(const char *pluginname __hwloc_attribute_unused, const char *symbol __hwloc_attribute_unused)
    -
    448 {
    -
    449 #ifdef HWLOC_INSIDE_PLUGIN
    -
    450  void *sym;
    -
    451 #ifdef HWLOC_HAVE_LTDL
    -
    452  lt_dlhandle handle = lt_dlopen(NULL);
    -
    453 #else
    -
    454  void *handle = dlopen(NULL, RTLD_NOW|RTLD_LOCAL);
    -
    455 #endif
    -
    456  if (!handle)
    -
    457  /* cannot check, assume things will work */
    -
    458  return 0;
    -
    459 #ifdef HWLOC_HAVE_LTDL
    -
    460  sym = lt_dlsym(handle, symbol);
    -
    461  lt_dlclose(handle);
    -
    462 #else
    -
    463  sym = dlsym(handle, symbol);
    -
    464  dlclose(handle);
    -
    465 #endif
    -
    466  if (!sym) {
    -
    467  static int verboseenv_checked = 0;
    -
    468  static int verboseenv_value = 0;
    -
    469  if (!verboseenv_checked) {
    -
    470  const char *verboseenv = getenv("HWLOC_PLUGINS_VERBOSE");
    -
    471  verboseenv_value = verboseenv ? atoi(verboseenv) : 0;
    -
    472  verboseenv_checked = 1;
    -
    473  }
    -
    474  if (verboseenv_value)
    -
    475  fprintf(stderr, "Plugin `%s' disabling itself because it cannot find the `%s' core symbol.\n",
    -
    476  pluginname, symbol);
    -
    477  return -1;
    -
    478  }
    -
    479 #endif /* HWLOC_INSIDE_PLUGIN */
    -
    480  return 0;
    -
    481 }
    -
    482 
    -
    499 static __hwloc_inline int
    -
    500 hwloc_filter_check_pcidev_subtype_important(unsigned classid)
    -
    501 {
    -
    502  unsigned baseclass = classid >> 8;
    -
    503  return (baseclass == 0x03 /* PCI_BASE_CLASS_DISPLAY */
    -
    504  || baseclass == 0x02 /* PCI_BASE_CLASS_NETWORK */
    -
    505  || baseclass == 0x01 /* PCI_BASE_CLASS_STORAGE */
    -
    506  || baseclass == 0x00 /* Unclassified, for Atos/Bull BXI */
    -
    507  || baseclass == 0x0b /* PCI_BASE_CLASS_PROCESSOR */
    -
    508  || classid == 0x0c04 /* PCI_CLASS_SERIAL_FIBER */
    -
    509  || classid == 0x0c06 /* PCI_CLASS_SERIAL_INFINIBAND */
    -
    510  || classid == 0x0502 /* PCI_CLASS_MEMORY_CXL */
    -
    511  || baseclass == 0x06 /* PCI_BASE_CLASS_BRIDGE with non-PCI downstream. the core will drop the useless ones later */
    -
    512  || baseclass == 0x12 /* Processing Accelerators */);
    -
    513 }
    -
    514 
    -
    519 static __hwloc_inline int
    -
    520 hwloc_filter_check_osdev_subtype_important(hwloc_obj_osdev_type_t subtype)
    -
    521 {
    -
    522  return (subtype != HWLOC_OBJ_OSDEV_DMA);
    -
    523 }
    -
    524 
    -
    531 static __hwloc_inline int
    -
    532 hwloc_filter_check_keep_object_type(hwloc_topology_t topology, hwloc_obj_type_t type)
    -
    533 {
    -
    534  enum hwloc_type_filter_e filter = HWLOC_TYPE_FILTER_KEEP_NONE;
    -
    535  hwloc_topology_get_type_filter(topology, type, &filter);
    -
    536  assert(filter != HWLOC_TYPE_FILTER_KEEP_IMPORTANT); /* IMPORTANT only used for I/O */
    -
    537  return filter == HWLOC_TYPE_FILTER_KEEP_NONE ? 0 : 1;
    -
    538 }
    -
    539 
    -
    544 static __hwloc_inline int
    -
    545 hwloc_filter_check_keep_object(hwloc_topology_t topology, hwloc_obj_t obj)
    -
    546 {
    -
    547  hwloc_obj_type_t type = obj->type;
    -
    548  enum hwloc_type_filter_e filter = HWLOC_TYPE_FILTER_KEEP_NONE;
    -
    549  hwloc_topology_get_type_filter(topology, type, &filter);
    -
    550  if (filter == HWLOC_TYPE_FILTER_KEEP_NONE)
    -
    551  return 0;
    -
    552  if (filter == HWLOC_TYPE_FILTER_KEEP_IMPORTANT) {
    -
    553  if (type == HWLOC_OBJ_PCI_DEVICE)
    -
    554  return hwloc_filter_check_pcidev_subtype_important(obj->attr->pcidev.class_id);
    -
    555  if (type == HWLOC_OBJ_OS_DEVICE)
    -
    556  return hwloc_filter_check_osdev_subtype_important(obj->attr->osdev.type);
    -
    557  }
    -
    558  return 1;
    -
    559 }
    -
    560 
    -
    577 HWLOC_DECLSPEC unsigned hwloc_pcidisc_find_cap(const unsigned char *config, unsigned cap);
    -
    578 
    -
    584 HWLOC_DECLSPEC int hwloc_pcidisc_find_linkspeed(const unsigned char *config, unsigned offset, float *linkspeed);
    -
    585 
    -
    590 HWLOC_DECLSPEC hwloc_obj_type_t hwloc_pcidisc_check_bridge_type(unsigned device_class, const unsigned char *config);
    -
    591 
    -
    598 HWLOC_DECLSPEC int hwloc_pcidisc_find_bridge_buses(unsigned domain, unsigned bus, unsigned dev, unsigned func,
    -
    599  unsigned *secondary_busp, unsigned *subordinate_busp,
    -
    600  const unsigned char *config);
    -
    601 
    -
    606 HWLOC_DECLSPEC void hwloc_pcidisc_tree_insert_by_busid(struct hwloc_obj **treep, struct hwloc_obj *obj);
    -
    607 
    -
    613 HWLOC_DECLSPEC int hwloc_pcidisc_tree_attach(struct hwloc_topology *topology, struct hwloc_obj *tree);
    -
    614 
    -
    638 HWLOC_DECLSPEC struct hwloc_obj * hwloc_pci_find_parent_by_busid(struct hwloc_topology *topology, unsigned domain, unsigned bus, unsigned dev, unsigned func);
    -
    639 
    -
    646 HWLOC_DECLSPEC struct hwloc_obj * hwloc_pci_find_by_busid(struct hwloc_topology *topology, unsigned domain, unsigned bus, unsigned dev, unsigned func);
    -
    647 
    -
    649 typedef void * hwloc_backend_distances_add_handle_t;
    -
    650 
    -
    657 HWLOC_DECLSPEC hwloc_backend_distances_add_handle_t
    -
    658 hwloc_backend_distances_add_create(hwloc_topology_t topology,
    -
    659  const char *name, unsigned long kind,
    -
    660  unsigned long flags);
    -
    661 
    -
    673 HWLOC_DECLSPEC int
    -
    674 hwloc_backend_distances_add_values(hwloc_topology_t topology,
    -
    675  hwloc_backend_distances_add_handle_t handle,
    -
    676  unsigned nbobjs, hwloc_obj_t *objs,
    -
    677  hwloc_uint64_t *values,
    -
    678  unsigned long flags);
    -
    679 
    -
    686 HWLOC_DECLSPEC int
    -
    687 hwloc_backend_distances_add_commit(hwloc_topology_t topology,
    -
    688  hwloc_backend_distances_add_handle_t handle,
    -
    689  unsigned long flags);
    -
    690 
    -
    696 #endif /* HWLOC_PLUGINS_H */
    -
    hwloc_obj_osdev_type_t
    enum hwloc_obj_osdev_type_e hwloc_obj_osdev_type_t
    Type of a OS device.
    -
    hwloc_obj_type_t
    hwloc_obj_type_t
    Type of topology object.
    Definition: hwloc.h:176
    -
    HWLOC_OBJ_OSDEV_DMA
    @ HWLOC_OBJ_OSDEV_DMA
    Operating system dma engine device. For instance the "dma0chan0" DMA channel on Linux.
    Definition: hwloc.h:351
    -
    HWLOC_OBJ_OS_DEVICE
    @ HWLOC_OBJ_OS_DEVICE
    Operating system device (filtered out by default).
    Definition: hwloc.h:279
    -
    HWLOC_OBJ_PCI_DEVICE
    @ HWLOC_OBJ_PCI_DEVICE
    PCI device (filtered out by default).
    Definition: hwloc.h:269
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:692
    -
    hwloc_topology_get_type_filter
    int hwloc_topology_get_type_filter(hwloc_topology_t topology, hwloc_obj_type_t type, enum hwloc_type_filter_e *filter)
    Get the current filtering for the given object type.
    -
    hwloc_type_filter_e
    hwloc_type_filter_e
    Type filtering flags.
    Definition: hwloc.h:2254
    -
    HWLOC_TYPE_FILTER_KEEP_NONE
    @ HWLOC_TYPE_FILTER_KEEP_NONE
    Ignore all objects of this type.
    Definition: hwloc.h:2268
    -
    HWLOC_TYPE_FILTER_KEEP_IMPORTANT
    @ HWLOC_TYPE_FILTER_KEEP_IMPORTANT
    Only keep likely-important objects of the given type.
    Definition: hwloc.h:2297
    -
    hwloc_bitmap_t
    struct hwloc_bitmap_s * hwloc_bitmap_t
    Set of bits represented as an opaque pointer to an internal bitmap.
    Definition: bitmap.h:68
    -
    hwloc_backend_enable
    int hwloc_backend_enable(struct hwloc_backend *backend)
    Enable a previously allocated and setup backend.
    -
    hwloc_disc_phase_t
    enum hwloc_disc_phase_e hwloc_disc_phase_t
    Discovery phase.
    -
    hwloc_disc_phase_e
    hwloc_disc_phase_e
    Discovery phase.
    Definition: plugins.h:106
    -
    hwloc_disc_status_flag_e
    hwloc_disc_status_flag_e
    Discovery status flags.
    Definition: plugins.h:146
    -
    hwloc_backend_alloc
    struct hwloc_backend * hwloc_backend_alloc(struct hwloc_topology *topology, struct hwloc_disc_component *component)
    Allocate a backend structure, set good default values, initialize backend->component and topology,...
    -
    HWLOC_DISC_PHASE_CPU
    @ HWLOC_DISC_PHASE_CPU
    CPU discovery.
    Definition: plugins.h:115
    -
    HWLOC_DISC_PHASE_PCI
    @ HWLOC_DISC_PHASE_PCI
    Attach PCI devices and bridges to existing CPU objects.
    Definition: plugins.h:123
    -
    HWLOC_DISC_PHASE_ANNOTATE
    @ HWLOC_DISC_PHASE_ANNOTATE
    Annotating existing objects, adding distances, etc.
    Definition: plugins.h:135
    -
    HWLOC_DISC_PHASE_MISC
    @ HWLOC_DISC_PHASE_MISC
    Misc objects that gets added below anything else.
    Definition: plugins.h:131
    -
    HWLOC_DISC_PHASE_IO
    @ HWLOC_DISC_PHASE_IO
    I/O discovery that requires PCI devices (OS devices such as OpenCL, CUDA, etc.).
    Definition: plugins.h:127
    -
    HWLOC_DISC_PHASE_GLOBAL
    @ HWLOC_DISC_PHASE_GLOBAL
    xml or synthetic, platform-specific components such as bgq. Discovers everything including CPU,...
    Definition: plugins.h:111
    -
    HWLOC_DISC_PHASE_MEMORY
    @ HWLOC_DISC_PHASE_MEMORY
    Attach memory to existing CPU objects.
    Definition: plugins.h:119
    -
    HWLOC_DISC_PHASE_TWEAK
    @ HWLOC_DISC_PHASE_TWEAK
    Final tweaks to a ready-to-use topology. This phase runs once the topology is loaded,...
    Definition: plugins.h:142
    -
    HWLOC_DISC_STATUS_FLAG_GOT_ALLOWED_RESOURCES
    @ HWLOC_DISC_STATUS_FLAG_GOT_ALLOWED_RESOURCES
    The sets of allowed resources were already retrieved.
    Definition: plugins.h:148
    -
    hwloc_component_type_t
    enum hwloc_component_type_e hwloc_component_type_t
    Generic component type.
    -
    hwloc_component_type_e
    hwloc_component_type_e
    Generic component type.
    Definition: plugins.h:257
    -
    HWLOC_COMPONENT_TYPE_DISC
    @ HWLOC_COMPONENT_TYPE_DISC
    The data field must point to a struct hwloc_disc_component.
    Definition: plugins.h:259
    -
    HWLOC_COMPONENT_TYPE_XML
    @ HWLOC_COMPONENT_TYPE_XML
    The data field must point to a struct hwloc_xml_component.
    Definition: plugins.h:262
    -
    hwloc_alloc_setup_object
    hwloc_obj_t hwloc_alloc_setup_object(hwloc_topology_t topology, hwloc_obj_type_t type, unsigned os_index)
    Allocate and initialize an object of the given type and physical index.
    -
    hwloc_insert_object_by_parent
    void hwloc_insert_object_by_parent(struct hwloc_topology *topology, hwloc_obj_t parent, hwloc_obj_t obj)
    Insert an object somewhere in the topology.
    -
    hwloc_topology_reconnect
    int hwloc_topology_reconnect(hwloc_topology_t topology, unsigned long flags)
    Request a reconnection of children and levels in the topology.
    -
    hwloc__insert_object_by_cpuset
    hwloc_obj_t hwloc__insert_object_by_cpuset(struct hwloc_topology *topology, hwloc_obj_t root, hwloc_obj_t obj, const char *reason)
    Add an object to the topology.
    -
    hwloc_obj_add_children_sets
    int hwloc_obj_add_children_sets(hwloc_obj_t obj)
    Setup object cpusets/nodesets by OR'ing its children.
    -
    hwloc_hide_errors
    int hwloc_hide_errors(void)
    Check whether error messages are hidden.
    -
    hwloc_plugin_check_namespace
    static int hwloc_plugin_check_namespace(const char *pluginname, const char *symbol)
    Make sure that plugins can lookup core symbols.
    Definition: plugins.h:447
    -
    hwloc_filter_check_keep_object_type
    static int hwloc_filter_check_keep_object_type(hwloc_topology_t topology, hwloc_obj_type_t type)
    Check whether a non-I/O object type should be filtered-out.
    Definition: plugins.h:532
    -
    hwloc_filter_check_keep_object
    static int hwloc_filter_check_keep_object(hwloc_topology_t topology, hwloc_obj_t obj)
    Check whether the given object should be filtered-out.
    Definition: plugins.h:545
    -
    hwloc_filter_check_pcidev_subtype_important
    static int hwloc_filter_check_pcidev_subtype_important(unsigned classid)
    Check whether the given PCI device classid is important.
    Definition: plugins.h:500
    -
    hwloc_filter_check_osdev_subtype_important
    static int hwloc_filter_check_osdev_subtype_important(hwloc_obj_osdev_type_t subtype)
    Check whether the given OS device subtype is important.
    Definition: plugins.h:520
    -
    hwloc_pcidisc_find_linkspeed
    int hwloc_pcidisc_find_linkspeed(const unsigned char *config, unsigned offset, float *linkspeed)
    Fill linkspeed by reading the PCI config space where PCI_CAP_ID_EXP is at position offset.
    -
    hwloc_pcidisc_check_bridge_type
    hwloc_obj_type_t hwloc_pcidisc_check_bridge_type(unsigned device_class, const unsigned char *config)
    Return the hwloc object type (PCI device or Bridge) for the given class and configuration space.
    -
    hwloc_pcidisc_find_cap
    unsigned hwloc_pcidisc_find_cap(const unsigned char *config, unsigned cap)
    Return the offset of the given capability in the PCI config space buffer.
    -
    hwloc_pcidisc_find_bridge_buses
    int hwloc_pcidisc_find_bridge_buses(unsigned domain, unsigned bus, unsigned dev, unsigned func, unsigned *secondary_busp, unsigned *subordinate_busp, const unsigned char *config)
    Fills the attributes of the given PCI bridge using the given PCI config space.
    -
    hwloc_pcidisc_tree_insert_by_busid
    void hwloc_pcidisc_tree_insert_by_busid(struct hwloc_obj **treep, struct hwloc_obj *obj)
    Insert a PCI object in the given PCI tree by looking at PCI bus IDs.
    -
    hwloc_pcidisc_tree_attach
    int hwloc_pcidisc_tree_attach(struct hwloc_topology *topology, struct hwloc_obj *tree)
    Add some hostbridges on top of the given tree of PCI objects and attach them to the topology.
    -
    hwloc_backend_distances_add_commit
    int hwloc_backend_distances_add_commit(hwloc_topology_t topology, hwloc_backend_distances_add_handle_t handle, unsigned long flags)
    Commit a new distances structure.
    -
    hwloc_pci_find_by_busid
    struct hwloc_obj * hwloc_pci_find_by_busid(struct hwloc_topology *topology, unsigned domain, unsigned bus, unsigned dev, unsigned func)
    Find the PCI device or bridge matching a PCI bus ID exactly.
    -
    hwloc_pci_find_parent_by_busid
    struct hwloc_obj * hwloc_pci_find_parent_by_busid(struct hwloc_topology *topology, unsigned domain, unsigned bus, unsigned dev, unsigned func)
    Find the object or a parent of a PCI bus ID.
    -
    hwloc_backend_distances_add_values
    int hwloc_backend_distances_add_values(hwloc_topology_t topology, hwloc_backend_distances_add_handle_t handle, unsigned nbobjs, hwloc_obj_t *objs, hwloc_uint64_t *values, unsigned long flags)
    Specify the objects and values in a new empty distances structure.
    -
    hwloc_backend_distances_add_create
    hwloc_backend_distances_add_handle_t hwloc_backend_distances_add_create(hwloc_topology_t topology, const char *name, unsigned long kind, unsigned long flags)
    Create a new empty distances structure.
    -
    hwloc_backend_distances_add_handle_t
    void * hwloc_backend_distances_add_handle_t
    Handle to a new distances structure during its addition to the topology.
    Definition: plugins.h:649
    -
    hwloc_obj
    Structure of a topology object.
    Definition: hwloc.h:396
    -
    hwloc_obj::name
    char * name
    Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name str...
    Definition: hwloc.h:408
    -
    hwloc_obj::type
    hwloc_obj_type_t type
    Type of object.
    Definition: hwloc.h:398
    -
    hwloc_obj::attr
    union hwloc_obj_attr_u * attr
    Object type-specific Attributes, may be NULL if no attribute value was found.
    Definition: hwloc.h:415
    -
    hwloc_obj_attr_u::pcidev
    struct hwloc_obj_attr_u::hwloc_pcidev_attr_s pcidev
    -
    hwloc_obj_attr_u::osdev
    struct hwloc_obj_attr_u::hwloc_osdev_attr_s osdev
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::class_id
    unsigned short class_id
    Definition: hwloc.h:640
    -
    hwloc_obj_attr_u::hwloc_osdev_attr_s::type
    hwloc_obj_osdev_type_t type
    Definition: hwloc.h:666
    -
    hwloc_disc_component
    Discovery component structure.
    Definition: plugins.h:41
    -
    hwloc_disc_component::name
    const char * name
    Name. If this component is built as a plugin, this name does not have to match the plugin filename.
    Definition: plugins.h:45
    -
    hwloc_disc_component::phases
    unsigned phases
    Discovery phases performed by this component. OR'ed set of hwloc_disc_phase_t.
    Definition: plugins.h:50
    -
    hwloc_disc_component::excluded_phases
    unsigned excluded_phases
    Component phases to exclude, as an OR'ed set of hwloc_disc_phase_t.
    Definition: plugins.h:60
    -
    hwloc_disc_component::enabled_by_default
    unsigned enabled_by_default
    Enabled by default. If unset, if will be disabled unless explicitly requested.
    Definition: plugins.h:84
    -
    hwloc_disc_component::priority
    unsigned priority
    Component priority. Used to sort topology->components, higher priority first. Also used to decide bet...
    Definition: plugins.h:79
    -
    hwloc_disc_status
    Discovery status structure.
    Definition: plugins.h:156
    -
    hwloc_disc_status::excluded_phases
    unsigned excluded_phases
    Dynamically excluded phases. If a component decides during discovery that some phases are no longer n...
    Definition: plugins.h:165
    -
    hwloc_disc_status::phase
    hwloc_disc_phase_t phase
    The current discovery phase that is performed. Must match one of the phases in the component phases f...
    Definition: plugins.h:160
    -
    hwloc_disc_status::flags
    unsigned long flags
    OR'ed set of hwloc_disc_status_flag_e.
    Definition: plugins.h:168
    -
    hwloc_backend
    Discovery backend structure.
    Definition: plugins.h:189
    -
    hwloc_backend::private_data
    void * private_data
    Backend private data, or NULL if none.
    Definition: plugins.h:216
    -
    hwloc_backend::disable
    void(* disable)(struct hwloc_backend *backend)
    Callback for freeing the private_data. May be NULL.
    Definition: plugins.h:220
    -
    hwloc_backend::flags
    unsigned long flags
    Backend flags, currently always 0.
    Definition: plugins.h:205
    -
    hwloc_backend::get_pci_busid_cpuset
    int(* get_pci_busid_cpuset)(struct hwloc_backend *backend, struct hwloc_pcidev_attr_s *busid, hwloc_bitmap_t cpuset)
    Callback to retrieve the locality of a PCI object. Called by the PCI core when attaching PCI hierarch...
    Definition: plugins.h:233
    -
    hwloc_backend::is_thissystem
    int is_thissystem
    Backend-specific 'is_thissystem' property. Set to 0 if the backend disables the thissystem flag for t...
    Definition: plugins.h:213
    -
    hwloc_backend::discover
    int(* discover)(struct hwloc_backend *backend, struct hwloc_disc_status *status)
    Main discovery callback. returns -1 on error, either because it couldn't add its objects ot the exist...
    Definition: plugins.h:227
    -
    hwloc_backend::phases
    unsigned phases
    Discovery phases performed by this component, possibly without some of them if excluded by other comp...
    Definition: plugins.h:202
    -
    hwloc_component
    Generic component structure.
    Definition: plugins.h:270
    -
    hwloc_component::abi
    unsigned abi
    Component ABI version, set to HWLOC_COMPONENT_ABI.
    Definition: plugins.h:272
    -
    hwloc_component::finalize
    void(* finalize)(unsigned long flags)
    Process-wide component termination callback.
    Definition: plugins.h:304
    -
    hwloc_component::data
    void * data
    Component data, pointing to a struct hwloc_disc_component or struct hwloc_xml_component.
    Definition: plugins.h:313
    -
    hwloc_component::type
    hwloc_component_type_t type
    Component type.
    Definition: plugins.h:307
    -
    hwloc_component::flags
    unsigned long flags
    Component flags, unused for now.
    Definition: plugins.h:310
    -
    hwloc_component::init
    int(* init)(unsigned long flags)
    Process-wide component initialization callback.
    Definition: plugins.h:291
    -
    - - - - - - - - -
    -
    -
    netloc.h
    -
    -
    -
    1 /*
    -
    2  * Copyright © 2013-2014 Cisco Systems, Inc. All rights reserved.
    -
    3  * Copyright © 2013-2014 University of Wisconsin-La Crosse.
    -
    4  * All rights reserved.
    -
    5  * Copyright © 2015-2016 Inria. All rights reserved.
    -
    6  *
    -
    7  * $COPYRIGHT$
    -
    8  *
    -
    9  * Additional copyrights may follow
    -
    10  * See COPYING in top-level directory.
    -
    11  *
    -
    12  * $HEADER$
    -
    13  */
    -
    14 
    -
    15 #ifndef _NETLOC_H_
    -
    16 #define _NETLOC_H_
    -
    17 
    -
    18 #ifndef _GNU_SOURCE
    -
    19 #define _GNU_SOURCE // for asprintf
    -
    20 #endif
    -
    21 
    -
    22 #include <hwloc/autogen/config.h>
    -
    23 
    -
    24 #include <hwloc.h>
    -
    25 
    -
    26 #ifdef __cplusplus
    -
    27 extern "C" {
    -
    28 #endif
    -
    29 
    -
    36 enum {
    -
    37  NETLOC_SUCCESS = 0,
    -
    38  NETLOC_ERROR = -1,
    -
    39  NETLOC_ERROR_NOTDIR = -2,
    -
    40  NETLOC_ERROR_NOENT = -3,
    -
    41  NETLOC_ERROR_EMPTY = -4,
    -
    42  NETLOC_ERROR_MULTIPLE = -5,
    -
    43  NETLOC_ERROR_NOT_IMPL = -6,
    -
    44  NETLOC_ERROR_EXISTS = -7,
    -
    45  NETLOC_ERROR_NOT_FOUND = -8,
    -
    46  NETLOC_ERROR_MAX = -9
    -
    47 };
    -
    48 
    -
    49 
    -
    50 #ifdef __cplusplus
    -
    51 } /* extern "C" */
    -
    52 #endif
    -
    53 
    -
    56 #endif // _NETLOC_H_
    -
    NETLOC_ERROR_EMPTY
    @ NETLOC_ERROR_EMPTY
    Definition: netloc.h:41
    -
    NETLOC_ERROR_MAX
    @ NETLOC_ERROR_MAX
    Definition: netloc.h:46
    -
    NETLOC_ERROR_MULTIPLE
    @ NETLOC_ERROR_MULTIPLE
    Definition: netloc.h:42
    -
    NETLOC_ERROR_NOT_IMPL
    @ NETLOC_ERROR_NOT_IMPL
    Definition: netloc.h:43
    -
    NETLOC_ERROR
    @ NETLOC_ERROR
    Definition: netloc.h:38
    -
    NETLOC_SUCCESS
    @ NETLOC_SUCCESS
    Definition: netloc.h:37
    -
    NETLOC_ERROR_NOT_FOUND
    @ NETLOC_ERROR_NOT_FOUND
    Definition: netloc.h:45
    -
    NETLOC_ERROR_EXISTS
    @ NETLOC_ERROR_EXISTS
    Definition: netloc.h:44
    -
    NETLOC_ERROR_NOTDIR
    @ NETLOC_ERROR_NOTDIR
    Definition: netloc.h:39
    -
    NETLOC_ERROR_NOENT
    @ NETLOC_ERROR_NOENT
    Definition: netloc.h:40
    -
    - - - - - - - -
    -
    -Macros | -Functions
    -
    -
    API version
    -
    -
    - - - - - - -

    -Macros

    #define HWLOC_API_VERSION   0x00020800
     
    #define HWLOC_COMPONENT_ABI   7
     
    - - - -

    -Functions

    unsigned hwloc_get_api_version (void)
     
    -

    Detailed Description

    -

    Macro Definition Documentation

    - -

    ◆ HWLOC_API_VERSION

    - -
    -
    - - - - -
    #define HWLOC_API_VERSION   0x00020800
    -
    - -

    Indicate at build time which hwloc API version is being used.

    -

    This number is updated to (X<<16)+(Y<<8)+Z when a new release X.Y.Z actually modifies the API.

    -

    Users may check for available features at build time using this number (see How do I handle API changes?).

    -
    Note
    This should not be confused with HWLOC_VERSION, the library version. Two stable releases of the same series usually have the same HWLOC_API_VERSION even if their HWLOC_VERSION are different.
    - -
    -
    - -

    ◆ HWLOC_COMPONENT_ABI

    - -
    -
    - - - - -
    #define HWLOC_COMPONENT_ABI   7
    -
    - -

    Current component and plugin ABI version (see hwloc/plugins.h)

    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_get_api_version()

    - -
    -
    - - - - - - - - -
    unsigned hwloc_get_api_version (void )
    -
    - -

    Indicate at runtime which hwloc API version was used at build time.

    -

    Should be HWLOC_API_VERSION if running on the same version.

    - -
    -
    -
    - - - - - - - -
    -
    -Typedefs
    -
    -
    Object Sets (hwloc_cpuset_t and hwloc_nodeset_t)
    -
    -
    - - - - - - - - - - -

    -Typedefs

    typedef hwloc_bitmap_t hwloc_cpuset_t
     
    typedef hwloc_const_bitmap_t hwloc_const_cpuset_t
     
    typedef hwloc_bitmap_t hwloc_nodeset_t
     
    typedef hwloc_const_bitmap_t hwloc_const_nodeset_t
     
    -

    Detailed Description

    -

    Hwloc uses bitmaps to represent two distinct kinds of object sets: CPU sets (hwloc_cpuset_t) and NUMA node sets (hwloc_nodeset_t). These types are both typedefs to a common back end type (hwloc_bitmap_t), and therefore all the hwloc bitmap functions are applicable to both hwloc_cpuset_t and hwloc_nodeset_t (see The bitmap API).

    -

    The rationale for having two different types is that even though the actions one wants to perform on these types are the same (e.g., enable and disable individual items in the set/mask), they're used in very different contexts: one for specifying which processors to use and one for specifying which NUMA nodes to use. Hence, the name difference is really just to reflect the intent of where the type is used.

    -

    Typedef Documentation

    - -

    ◆ hwloc_const_cpuset_t

    - -
    -
    - - - - -
    typedef hwloc_const_bitmap_t hwloc_const_cpuset_t
    -
    - -

    A non-modifiable hwloc_cpuset_t.

    - -
    -
    - -

    ◆ hwloc_const_nodeset_t

    - -
    -
    - - - - -
    typedef hwloc_const_bitmap_t hwloc_const_nodeset_t
    -
    - -

    A non-modifiable hwloc_nodeset_t.

    - -
    -
    - -

    ◆ hwloc_cpuset_t

    - -
    -
    - - - - -
    typedef hwloc_bitmap_t hwloc_cpuset_t
    -
    - -

    A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.

    -

    It may be consulted and modified with the bitmap API as any hwloc_bitmap_t (see hwloc/bitmap.h).

    -

    Each bit may be converted into a PU object using hwloc_get_pu_obj_by_os_index().

    - -
    -
    - -

    ◆ hwloc_nodeset_t

    - -
    -
    - - - - -
    typedef hwloc_bitmap_t hwloc_nodeset_t
    -
    - -

    A node set is a bitmap whose bits are set according to NUMA memory node physical OS indexes.

    -

    It may be consulted and modified with the bitmap API as any hwloc_bitmap_t (see hwloc/bitmap.h). Each bit may be converted into a NUMA node object using hwloc_get_numanode_obj_by_os_index().

    -

    When binding memory on a system without any NUMA node, the single main memory bank is considered as NUMA node #0.

    -

    See also Converting between CPU sets and node sets.

    - -
    -
    -
    - - - - - - - -
    -
    -Macros | -Typedefs | -Enumerations | -Functions
    -
    -
    Object Types
    -
    -
    - - - - -

    -Macros

    #define HWLOC_TYPE_UNORDERED
     
    - - - - - - - -

    -Typedefs

    typedef enum hwloc_obj_cache_type_e hwloc_obj_cache_type_t
     
    typedef enum hwloc_obj_bridge_type_e hwloc_obj_bridge_type_t
     
    typedef enum hwloc_obj_osdev_type_e hwloc_obj_osdev_type_t
     
    - - - - - - - - - -

    -Enumerations

    enum  hwloc_obj_type_t {
    -  HWLOC_OBJ_MACHINE -, HWLOC_OBJ_PACKAGE -, HWLOC_OBJ_CORE -, HWLOC_OBJ_PU -,
    -  HWLOC_OBJ_L1CACHE -, HWLOC_OBJ_L2CACHE -, HWLOC_OBJ_L3CACHE -, HWLOC_OBJ_L4CACHE -,
    -  HWLOC_OBJ_L5CACHE -, HWLOC_OBJ_L1ICACHE -, HWLOC_OBJ_L2ICACHE -, HWLOC_OBJ_L3ICACHE -,
    -  HWLOC_OBJ_GROUP -, HWLOC_OBJ_NUMANODE -, HWLOC_OBJ_BRIDGE -, HWLOC_OBJ_PCI_DEVICE -,
    -  HWLOC_OBJ_OS_DEVICE -, HWLOC_OBJ_MISC -, HWLOC_OBJ_MEMCACHE -, HWLOC_OBJ_DIE -,
    -  HWLOC_OBJ_TYPE_MAX -
    - }
     
    enum  hwloc_obj_cache_type_e { HWLOC_OBJ_CACHE_UNIFIED -, HWLOC_OBJ_CACHE_DATA -, HWLOC_OBJ_CACHE_INSTRUCTION - }
     
    enum  hwloc_obj_bridge_type_e { HWLOC_OBJ_BRIDGE_HOST -, HWLOC_OBJ_BRIDGE_PCI - }
     
    enum  hwloc_obj_osdev_type_e {
    -  HWLOC_OBJ_OSDEV_BLOCK -, HWLOC_OBJ_OSDEV_GPU -, HWLOC_OBJ_OSDEV_NETWORK -, HWLOC_OBJ_OSDEV_OPENFABRICS -,
    -  HWLOC_OBJ_OSDEV_DMA -, HWLOC_OBJ_OSDEV_COPROC -
    - }
     
    - - - -

    -Functions

    int hwloc_compare_types (hwloc_obj_type_t type1, hwloc_obj_type_t type2)
     
    -

    Detailed Description

    -

    Macro Definition Documentation

    - -

    ◆ HWLOC_TYPE_UNORDERED

    - -
    -
    - - - - -
    #define HWLOC_TYPE_UNORDERED
    -
    - -

    Value returned by hwloc_compare_types() when types can not be compared.

    - -
    -
    -

    Typedef Documentation

    - -

    ◆ hwloc_obj_bridge_type_t

    - -
    -
    - - - - -
    typedef enum hwloc_obj_bridge_type_e hwloc_obj_bridge_type_t
    -
    - -

    Type of one side (upstream or downstream) of an I/O bridge.

    - -
    -
    - -

    ◆ hwloc_obj_cache_type_t

    - -
    -
    - - - - -
    typedef enum hwloc_obj_cache_type_e hwloc_obj_cache_type_t
    -
    - -

    Cache type.

    - -
    -
    - -

    ◆ hwloc_obj_osdev_type_t

    - -
    -
    - - - - -
    typedef enum hwloc_obj_osdev_type_e hwloc_obj_osdev_type_t
    -
    - -

    Type of a OS device.

    - -
    -
    -

    Enumeration Type Documentation

    - -

    ◆ hwloc_obj_bridge_type_e

    - -
    -
    - - - - -
    enum hwloc_obj_bridge_type_e
    -
    - -

    Type of one side (upstream or downstream) of an I/O bridge.

    - - - -
    Enumerator
    HWLOC_OBJ_BRIDGE_HOST 

    Host-side of a bridge, only possible upstream.

    -
    HWLOC_OBJ_BRIDGE_PCI 

    PCI-side of a bridge.

    -
    - -
    -
    - -

    ◆ hwloc_obj_cache_type_e

    - -
    -
    - - - - -
    enum hwloc_obj_cache_type_e
    -
    - -

    Cache type.

    - - - - -
    Enumerator
    HWLOC_OBJ_CACHE_UNIFIED 

    Unified cache.

    -
    HWLOC_OBJ_CACHE_DATA 

    Data cache.

    -
    HWLOC_OBJ_CACHE_INSTRUCTION 

    Instruction cache (filtered out by default).

    -
    - -
    -
    - -

    ◆ hwloc_obj_osdev_type_e

    - -
    -
    - - - - -
    enum hwloc_obj_osdev_type_e
    -
    - -

    Type of a OS device.

    - - - - - - - -
    Enumerator
    HWLOC_OBJ_OSDEV_BLOCK 

    Operating system block device, or non-volatile memory device. For instance "sda" or "dax2.0" on Linux.

    -
    HWLOC_OBJ_OSDEV_GPU 

    Operating system GPU device. For instance ":0.0" for a GL display, "card0" for a Linux DRM device.

    -
    HWLOC_OBJ_OSDEV_NETWORK 

    Operating system network device. For instance the "eth0" interface on Linux.

    -
    HWLOC_OBJ_OSDEV_OPENFABRICS 

    Operating system openfabrics device. For instance the "mlx4_0" InfiniBand HCA, "hfi1_0" Omni-Path interface, or "bxi0" Atos/Bull BXI HCA on Linux.

    -
    HWLOC_OBJ_OSDEV_DMA 

    Operating system dma engine device. For instance the "dma0chan0" DMA channel on Linux.

    -
    HWLOC_OBJ_OSDEV_COPROC 

    Operating system co-processor device. For instance "opencl0d0" for a OpenCL device, "cuda0" for a CUDA device.

    -
    - -
    -
    - -

    ◆ hwloc_obj_type_t

    - -
    -
    - - - - -
    enum hwloc_obj_type_t
    -
    - -

    Type of topology object.

    -
    Note
    Do not rely on the ordering or completeness of the values as new ones may be defined in the future! If you need to compare types, use hwloc_compare_types() instead.
    - - - - - - - - - - - - - - - - - - - - - -
    Enumerator
    HWLOC_OBJ_MACHINE 

    Machine. A set of processors and memory with cache coherency.

    -

    This type is always used for the root object of a topology, and never used anywhere else. Hence its parent is always NULL.

    -
    HWLOC_OBJ_PACKAGE 

    Physical package. The physical package that usually gets inserted into a socket on the motherboard. A processor package usually contains multiple cores, and possibly some dies.

    -
    HWLOC_OBJ_CORE 

    Core. A computation unit (may be shared by several PUs, aka logical processors).

    -
    HWLOC_OBJ_PU 

    Processing Unit, or (Logical) Processor. An execution unit (may share a core with some other logical processors, e.g. in the case of an SMT core).

    -

    This is the smallest object representing CPU resources, it cannot have any child except Misc objects.

    -

    Objects of this kind are always reported and can thus be used as fallback when others are not.

    -
    HWLOC_OBJ_L1CACHE 

    Level 1 Data (or Unified) Cache.

    -
    HWLOC_OBJ_L2CACHE 

    Level 2 Data (or Unified) Cache.

    -
    HWLOC_OBJ_L3CACHE 

    Level 3 Data (or Unified) Cache.

    -
    HWLOC_OBJ_L4CACHE 

    Level 4 Data (or Unified) Cache.

    -
    HWLOC_OBJ_L5CACHE 

    Level 5 Data (or Unified) Cache.

    -
    HWLOC_OBJ_L1ICACHE 

    Level 1 instruction Cache (filtered out by default).

    -
    HWLOC_OBJ_L2ICACHE 

    Level 2 instruction Cache (filtered out by default).

    -
    HWLOC_OBJ_L3ICACHE 

    Level 3 instruction Cache (filtered out by default).

    -
    HWLOC_OBJ_GROUP 

    Group objects. Objects which do not fit in the above but are detected by hwloc and are useful to take into account for affinity. For instance, some operating systems expose their arbitrary processors aggregation this way. And hwloc may insert such objects to group NUMA nodes according to their distances. See also What are these Group objects in my topology?.

    -

    These objects are removed when they do not bring any structure (see HWLOC_TYPE_FILTER_KEEP_STRUCTURE).

    -
    HWLOC_OBJ_NUMANODE 

    NUMA node. An object that contains memory that is directly and byte-accessible to the host processors. It is usually close to some cores (the corresponding objects are descendants of the NUMA node object in the hwloc tree).

    -

    This is the smallest object representing Memory resources, it cannot have any child except Misc objects. However it may have Memory-side cache parents.

    -

    There is always at least one such object in the topology even if the machine is not NUMA.

    -

    Memory objects are not listed in the main children list, but rather in the dedicated Memory children list.

    -

    NUMA nodes have a special depth HWLOC_TYPE_DEPTH_NUMANODE instead of a normal depth just like other objects in the main tree.

    -
    HWLOC_OBJ_BRIDGE 

    Bridge (filtered out by default). Any bridge (or PCI switch) that connects the host or an I/O bus, to another I/O bus.

    -

    Bridges are not added to the topology unless their filtering is changed (see hwloc_topology_set_type_filter() and hwloc_topology_set_io_types_filter()).

    -

    I/O objects are not listed in the main children list, but rather in the dedicated io children list. I/O objects have NULL CPU and node sets.

    -
    HWLOC_OBJ_PCI_DEVICE 

    PCI device (filtered out by default).

    -

    PCI devices are not added to the topology unless their filtering is changed (see hwloc_topology_set_type_filter() and hwloc_topology_set_io_types_filter()).

    -

    I/O objects are not listed in the main children list, but rather in the dedicated io children list. I/O objects have NULL CPU and node sets.

    -
    HWLOC_OBJ_OS_DEVICE 

    Operating system device (filtered out by default).

    -

    OS devices are not added to the topology unless their filtering is changed (see hwloc_topology_set_type_filter() and hwloc_topology_set_io_types_filter()).

    -

    I/O objects are not listed in the main children list, but rather in the dedicated io children list. I/O objects have NULL CPU and node sets.

    -
    HWLOC_OBJ_MISC 

    Miscellaneous objects (filtered out by default). Objects without particular meaning, that can e.g. be added by the application for its own use, or by hwloc for miscellaneous objects such as MemoryModule (DIMMs).

    -

    They are not added to the topology unless their filtering is changed (see hwloc_topology_set_type_filter()).

    -

    These objects are not listed in the main children list, but rather in the dedicated misc children list. Misc objects may only have Misc objects as children, and those are in the dedicated misc children list as well. Misc objects have NULL CPU and node sets.

    -
    HWLOC_OBJ_MEMCACHE 

    Memory-side cache (filtered out by default). A cache in front of a specific NUMA node.

    -

    This object always has at least one NUMA node as a memory child.

    -

    Memory objects are not listed in the main children list, but rather in the dedicated Memory children list.

    -

    Memory-side cache have a special depth HWLOC_TYPE_DEPTH_MEMCACHE instead of a normal depth just like other objects in the main tree.

    -
    HWLOC_OBJ_DIE 

    Die within a physical package. A subpart of the physical package, that contains multiple cores.

    -
    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_compare_types()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_compare_types (hwloc_obj_type_t type1,
    hwloc_obj_type_t type2 
    )
    -
    - -

    Compare the depth of two object types.

    -

    Types shouldn't be compared as they are, since newer ones may be added in the future. This function returns less than, equal to, or greater than zero respectively if type1 objects usually include type2 objects, are the same as type2 objects, or are included in type2 objects. If the types can not be compared (because neither is usually contained in the other), HWLOC_TYPE_UNORDERED is returned. Object types containing CPUs can always be compared (usually, a system contains machines which contain nodes which contain packages which contain caches, which contain cores, which contain processors).

    -
    Note
    HWLOC_OBJ_PU will always be the deepest, while HWLOC_OBJ_MACHINE is always the highest.
    -
    -This does not mean that the actual topology will respect that order: e.g. as of today cores may also contain caches, and packages may also contain nodes. This is thus just to be seen as a fallback comparison method.
    - -
    -
    -
    - - - - - - - -
    -
    -Data Structures | -Typedefs
    -
    -
    Object Structure and Attributes
    -
    -
    - - - - - - - - -

    -Data Structures

    struct  hwloc_obj
     
    union  hwloc_obj_attr_u
     
    struct  hwloc_info_s
     
    - - - -

    -Typedefs

    typedef struct hwloc_obj * hwloc_obj_t
     
    -

    Detailed Description

    -

    Typedef Documentation

    - -

    ◆ hwloc_obj_t

    - -
    -
    - - - - -
    typedef struct hwloc_obj* hwloc_obj_t
    -
    - -

    Convenience typedef; a pointer to a struct hwloc_obj.

    - -
    -
    -
    - - - - - - - -
    -
    -Typedefs | -Functions
    -
    -
    Topology Creation and Destruction
    -
    -
    - - - - -

    -Typedefs

    typedef struct hwloc_topology * hwloc_topology_t
     
    - - - - - - - - - - - - - -

    -Functions

    int hwloc_topology_init (hwloc_topology_t *topologyp)
     
    int hwloc_topology_load (hwloc_topology_t topology)
     
    void hwloc_topology_destroy (hwloc_topology_t topology)
     
    int hwloc_topology_dup (hwloc_topology_t *newtopology, hwloc_topology_t oldtopology)
     
    int hwloc_topology_abi_check (hwloc_topology_t topology)
     
    void hwloc_topology_check (hwloc_topology_t topology)
     
    -

    Detailed Description

    -

    Typedef Documentation

    - -

    ◆ hwloc_topology_t

    - -
    -
    - - - - -
    typedef struct hwloc_topology* hwloc_topology_t
    -
    - -

    Topology context.

    -

    To be initialized with hwloc_topology_init() and built with hwloc_topology_load().

    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_topology_abi_check()

    - -
    -
    - - - - - - - - -
    int hwloc_topology_abi_check (hwloc_topology_t topology)
    -
    - -

    Verify that the topology is compatible with the current hwloc library.

    -

    This is useful when using the same topology structure (in memory) in different libraries that may use different hwloc installations (for instance if one library embeds a specific version of hwloc, while another library uses a default system-wide hwloc installation).

    -

    If all libraries/programs use the same hwloc installation, this function always returns success.

    -
    Returns
    0 on success.
    -
    --1 with errno set to EINVAL if incompatible.
    -
    Note
    If sharing between processes with hwloc_shmem_topology_write(), the relevant check is already performed inside hwloc_shmem_topology_adopt().
    - -
    -
    - -

    ◆ hwloc_topology_check()

    - -
    -
    - - - - - - - - -
    void hwloc_topology_check (hwloc_topology_t topology)
    -
    - -

    Run internal checks on a topology structure.

    -

    The program aborts if an inconsistency is detected in the given topology.

    -
    Parameters
    - - -
    topologyis the topology to be checked
    -
    -
    -
    Note
    This routine is only useful to developers.
    -
    -The input topology should have been previously loaded with hwloc_topology_load().
    - -
    -
    - -

    ◆ hwloc_topology_destroy()

    - -
    -
    - - - - - - - - -
    void hwloc_topology_destroy (hwloc_topology_t topology)
    -
    - -

    Terminate and free a topology context.

    -
    Parameters
    - - -
    topologyis the topology to be freed
    -
    -
    - -
    -
    - -

    ◆ hwloc_topology_dup()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_dup (hwloc_topology_t * newtopology,
    hwloc_topology_t oldtopology 
    )
    -
    - -

    Duplicate a topology.

    -

    The entire topology structure as well as its objects are duplicated into a new one.

    -

    This is useful for keeping a backup while modifying a topology.

    -
    Note
    Object userdata is not duplicated since hwloc does not know what it point to. The objects of both old and new topologies will point to the same userdata.
    - -
    -
    - -

    ◆ hwloc_topology_init()

    - -
    -
    - - - - - - - - -
    int hwloc_topology_init (hwloc_topology_t * topologyp)
    -
    - -

    Allocate a topology context.

    -
    Parameters
    - - -
    [out]topologypis assigned a pointer to the new allocated context.
    -
    -
    -
    Returns
    0 on success, -1 on error.
    - -
    -
    - -

    ◆ hwloc_topology_load()

    - -
    -
    - - - - - - - - -
    int hwloc_topology_load (hwloc_topology_t topology)
    -
    - -

    Build the actual topology.

    -

    Build the actual topology once initialized with hwloc_topology_init() and tuned with Topology Detection Configuration and Query and Changing the Source of Topology Discovery routines. No other routine may be called earlier using this topology context.

    -
    Parameters
    - - -
    topologyis the topology to be loaded with objects.
    -
    -
    -
    Returns
    0 on success, -1 on error.
    -
    Note
    On failure, the topology is reinitialized. It should be either destroyed with hwloc_topology_destroy() or configured and loaded again.
    -
    -This function may be called only once per topology.
    -
    -The binding of the current thread or process may temporarily change during this call but it will be restored before it returns.
    -
    See also
    Topology Detection Configuration and Query and Changing the Source of Topology Discovery
    - -
    -
    -
    - - - - - - - -
    -
    -Enumerations | -Functions
    -
    -
    Object levels, depths and types
    -
    -
    - - - - -

    -Enumerations

    enum  hwloc_get_type_depth_e {
    -  HWLOC_TYPE_DEPTH_UNKNOWN -, HWLOC_TYPE_DEPTH_MULTIPLE -, HWLOC_TYPE_DEPTH_NUMANODE -, HWLOC_TYPE_DEPTH_BRIDGE -,
    -  HWLOC_TYPE_DEPTH_PCI_DEVICE -, HWLOC_TYPE_DEPTH_OS_DEVICE -, HWLOC_TYPE_DEPTH_MISC -, HWLOC_TYPE_DEPTH_MEMCACHE -
    - }
     
    - - - - - - - - - - - - - - - - - - - - - - - - - - - -

    -Functions

    int hwloc_topology_get_depth (hwloc_topology_t restrict topology)
     
    int hwloc_get_type_depth (hwloc_topology_t topology, hwloc_obj_type_t type)
     
    int hwloc_get_memory_parents_depth (hwloc_topology_t topology)
     
    static int hwloc_get_type_or_below_depth (hwloc_topology_t topology, hwloc_obj_type_t type)
     
    static int hwloc_get_type_or_above_depth (hwloc_topology_t topology, hwloc_obj_type_t type)
     
    hwloc_obj_type_t hwloc_get_depth_type (hwloc_topology_t topology, int depth)
     
    unsigned hwloc_get_nbobjs_by_depth (hwloc_topology_t topology, int depth)
     
    static int hwloc_get_nbobjs_by_type (hwloc_topology_t topology, hwloc_obj_type_t type)
     
    static hwloc_obj_t hwloc_get_root_obj (hwloc_topology_t topology)
     
    hwloc_obj_t hwloc_get_obj_by_depth (hwloc_topology_t topology, int depth, unsigned idx)
     
    static hwloc_obj_t hwloc_get_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx)
     
    static hwloc_obj_t hwloc_get_next_obj_by_depth (hwloc_topology_t topology, int depth, hwloc_obj_t prev)
     
    static hwloc_obj_t hwloc_get_next_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, hwloc_obj_t prev)
     
    -

    Detailed Description

    -

    Be sure to see the figure in Terms and Definitions that shows a complete topology tree, including depths, child/sibling/cousin relationships, and an example of an asymmetric topology where one package has fewer caches than its peers.

    -

    Enumeration Type Documentation

    - -

    ◆ hwloc_get_type_depth_e

    - -
    -
    - - - - -
    enum hwloc_get_type_depth_e
    -
    - - - - - - - - - -
    Enumerator
    HWLOC_TYPE_DEPTH_UNKNOWN 

    No object of given type exists in the topology.

    -
    HWLOC_TYPE_DEPTH_MULTIPLE 

    Objects of given type exist at different depth in the topology (only for Groups).

    -
    HWLOC_TYPE_DEPTH_NUMANODE 

    Virtual depth for NUMA nodes.

    -
    HWLOC_TYPE_DEPTH_BRIDGE 

    Virtual depth for bridge object level.

    -
    HWLOC_TYPE_DEPTH_PCI_DEVICE 

    Virtual depth for PCI device object level.

    -
    HWLOC_TYPE_DEPTH_OS_DEVICE 

    Virtual depth for software device object level.

    -
    HWLOC_TYPE_DEPTH_MISC 

    Virtual depth for Misc object.

    -
    HWLOC_TYPE_DEPTH_MEMCACHE 

    Virtual depth for MemCache object.

    -
    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_get_depth_type()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    hwloc_obj_type_t hwloc_get_depth_type (hwloc_topology_t topology,
    int depth 
    )
    -
    - -

    Returns the type of objects at depth depth.

    -

    depth should between 0 and hwloc_topology_get_depth()-1, or a virtual depth such as HWLOC_TYPE_DEPTH_NUMANODE.

    -
    Returns
    (hwloc_obj_type_t)-1 if depth depth does not exist.
    - -
    -
    - -

    ◆ hwloc_get_memory_parents_depth()

    - -
    -
    - - - - - - - - -
    int hwloc_get_memory_parents_depth (hwloc_topology_t topology)
    -
    - -

    Return the depth of parents where memory objects are attached.

    -

    Memory objects have virtual negative depths because they are not part of the main CPU-side hierarchy of objects. This depth should not be compared with other level depths.

    -

    If all Memory objects are attached to Normal parents at the same depth, this parent depth may be compared to other as usual, for instance for knowing whether NUMA nodes is attached above or below Packages.

    -
    Returns
    The depth of Normal parents of all memory children if all these parents have the same depth. For instance the depth of the Package level if all NUMA nodes are attached to Package objects.
    -
    -HWLOC_TYPE_DEPTH_MULTIPLE if Normal parents of all memory children do not have the same depth. For instance if some NUMA nodes are attached to Packages while others are attached to Groups.
    - -
    -
    - -

    ◆ hwloc_get_nbobjs_by_depth()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    unsigned hwloc_get_nbobjs_by_depth (hwloc_topology_t topology,
    int depth 
    )
    -
    - -

    Returns the width of level at depth depth.

    - -
    -
    - -

    ◆ hwloc_get_nbobjs_by_type()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static int hwloc_get_nbobjs_by_type (hwloc_topology_t topology,
    hwloc_obj_type_t type 
    )
    -     		-inlinestatic
    -
    - -

    Returns the width of level type type.

    -

    If no object for that type exists, 0 is returned. If there are several levels with objects of that type, -1 is returned.

    - -
    -
    - -

    ◆ hwloc_get_next_obj_by_depth()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_next_obj_by_depth (hwloc_topology_t topology,
    int depth,
    hwloc_obj_t prev 
    )
    -     		-inlinestatic
    -
    - -

    Returns the next object at depth depth.

    -

    If prev is NULL, return the first object at depth depth.

    - -
    -
    - -

    ◆ hwloc_get_next_obj_by_type()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_next_obj_by_type (hwloc_topology_t topology,
    hwloc_obj_type_t type,
    hwloc_obj_t prev 
    )
    -     		-inlinestatic
    -
    - -

    Returns the next object of type type.

    -

    If prev is NULL, return the first object at type type. If there are multiple or no depth for given type, return NULL and let the caller fallback to hwloc_get_next_obj_by_depth().

    - -
    -
    - -

    ◆ hwloc_get_obj_by_depth()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    hwloc_obj_t hwloc_get_obj_by_depth (hwloc_topology_t topology,
    int depth,
    unsigned idx 
    )
    -
    - -

    Returns the topology object at logical index idx from depth depth.

    - -
    -
    - -

    ◆ hwloc_get_obj_by_type()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_obj_by_type (hwloc_topology_t topology,
    hwloc_obj_type_t type,
    unsigned idx 
    )
    -     		-inlinestatic
    -
    - -

    Returns the topology object at logical index idx with type type.

    -

    If no object for that type exists, NULL is returned. If there are several levels with objects of that type (HWLOC_OBJ_GROUP), NULL is returned and the caller may fallback to hwloc_get_obj_by_depth().

    - -
    -
    - -

    ◆ hwloc_get_root_obj()

    - -
    -
    - - - - - -
    - - - - - - - - -
    static hwloc_obj_t hwloc_get_root_obj (hwloc_topology_t topology)
    -     		-inlinestatic
    -
    - -

    Returns the top-object of the topology-tree.

    -

    Its type is HWLOC_OBJ_MACHINE.

    - -
    -
    - -

    ◆ hwloc_get_type_depth()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_get_type_depth (hwloc_topology_t topology,
    hwloc_obj_type_t type 
    )
    -
    - -

    Returns the depth of objects of type type.

    -

    If no object of this type is present on the underlying architecture, or if the OS doesn't provide this kind of information, the function returns HWLOC_TYPE_DEPTH_UNKNOWN.

    -

    If type is absent but a similar type is acceptable, see also hwloc_get_type_or_below_depth() and hwloc_get_type_or_above_depth().

    -

    If HWLOC_OBJ_GROUP is given, the function may return HWLOC_TYPE_DEPTH_MULTIPLE if multiple levels of Groups exist.

    -

    If a NUMA node, I/O or Misc object type is given, the function returns a virtual value because these objects are stored in special levels that are not CPU-related. This virtual depth may be passed to other hwloc functions such as hwloc_get_obj_by_depth() but it should not be considered as an actual depth by the application. In particular, it should not be compared with any other object depth or with the entire topology depth.

    See also
    hwloc_get_memory_parents_depth().
    -
    -hwloc_type_sscanf_as_depth() for returning the depth of objects whose type is given as a string.
    - -
    -
    - -

    ◆ hwloc_get_type_or_above_depth()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static int hwloc_get_type_or_above_depth (hwloc_topology_t topology,
    hwloc_obj_type_t type 
    )
    -     		-inlinestatic
    -
    - -

    Returns the depth of objects of type type or above.

    -

    If no object of this type is present on the underlying architecture, the function returns the depth of the first "present" object typically containing type.

    -

    This function is only meaningful for normal object types. If a memory, I/O or Misc object type is given, the corresponding virtual depth is always returned (see hwloc_get_type_depth()).

    -

    May return HWLOC_TYPE_DEPTH_MULTIPLE for HWLOC_OBJ_GROUP just like hwloc_get_type_depth().

    - -
    -
    - -

    ◆ hwloc_get_type_or_below_depth()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static int hwloc_get_type_or_below_depth (hwloc_topology_t topology,
    hwloc_obj_type_t type 
    )
    -     		-inlinestatic
    -
    - -

    Returns the depth of objects of type type or below.

    -

    If no object of this type is present on the underlying architecture, the function returns the depth of the first "present" object typically found inside type.

    -

    This function is only meaningful for normal object types. If a memory, I/O or Misc object type is given, the corresponding virtual depth is always returned (see hwloc_get_type_depth()).

    -

    May return HWLOC_TYPE_DEPTH_MULTIPLE for HWLOC_OBJ_GROUP just like hwloc_get_type_depth().

    - -
    -
    - -

    ◆ hwloc_topology_get_depth()

    - -
    -
    - - - - - - - - -
    int hwloc_topology_get_depth (hwloc_topology_t restrict topology)
    -
    - -

    Get the depth of the hierarchical tree of objects.

    -

    This is the depth of HWLOC_OBJ_PU objects plus one.

    -
    Note
    NUMA nodes, I/O and Misc objects are ignored when computing the depth of the tree (they are placed on special levels).
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    -
    Converting between Object Types and Attributes, and Strings
    -
    -
    - - - - - - - - - - - - -

    -Functions

    const char * hwloc_obj_type_string (hwloc_obj_type_t type)
     
    int hwloc_obj_type_snprintf (char *restrict string, size_t size, hwloc_obj_t obj, int verbose)
     
    int hwloc_obj_attr_snprintf (char *restrict string, size_t size, hwloc_obj_t obj, const char *restrict separator, int verbose)
     
    int hwloc_type_sscanf (const char *string, hwloc_obj_type_t *typep, union hwloc_obj_attr_u *attrp, size_t attrsize)
     
    int hwloc_type_sscanf_as_depth (const char *string, hwloc_obj_type_t *typep, hwloc_topology_t topology, int *depthp)
     
    -

    Detailed Description

    -

    Function Documentation

    - -

    ◆ hwloc_obj_attr_snprintf()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_obj_attr_snprintf (char *restrict string,
    size_t size,
    hwloc_obj_t obj,
    const char *restrict separator,
    int verbose 
    )
    -
    - -

    Stringify the attributes of a given topology object into a human-readable form.

    -

    Attribute values are separated by separator.

    -

    Only the major attributes are printed in non-verbose mode.

    -

    If size is 0, string may safely be NULL.

    -
    Returns
    the number of characters that were actually written if not truncating, or that would have been written (not including the ending \0).
    - -
    -
    - -

    ◆ hwloc_obj_type_snprintf()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_obj_type_snprintf (char *restrict string,
    size_t size,
    hwloc_obj_t obj,
    int verbose 
    )
    -
    - -

    Stringify the type of a given topology object into a human-readable form.

    -

    Contrary to hwloc_obj_type_string(), this function includes object-specific attributes (such as the Group depth, the Bridge type, or OS device type) in the output, and it requires the caller to provide the output buffer.

    -

    The output is guaranteed to be the same for all objects of a same topology level.

    -

    If verbose is 1, longer type names are used, e.g. L1Cache instead of L1.

    -

    The output string may be parsed back by hwloc_type_sscanf().

    -

    If size is 0, string may safely be NULL.

    -
    Returns
    the number of characters that were actually written if not truncating, or that would have been written (not including the ending \0).
    - -
    -
    - -

    ◆ hwloc_obj_type_string()

    - -
    -
    - - - - - - - - -
    const char* hwloc_obj_type_string (hwloc_obj_type_t type)
    -
    - -

    Return a constant stringified object type.

    -

    This function is the basic way to convert a generic type into a string. The output string may be parsed back by hwloc_type_sscanf().

    -

    hwloc_obj_type_snprintf() may return a more precise output for a specific object, but it requires the caller to provide the output buffer.

    - -
    -
    - -

    ◆ hwloc_type_sscanf()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_type_sscanf (const char * string,
    hwloc_obj_type_t * typep,
    union hwloc_obj_attr_u * attrp,
    size_t attrsize 
    )
    -
    - -

    Return an object type and attributes from a type string.

    -

    Convert strings such as "Package" or "L1iCache" into the corresponding types. Matching is case-insensitive, and only the first letters are actually required to match.

    -

    The matched object type is set in typep (which cannot be NULL).

    -

    Type-specific attributes, for instance Cache type, Cache depth, Group depth, Bridge type or OS Device type may be returned in attrp. Attributes that are not specified in the string (for instance "Group" without a depth, or "L2Cache" without a cache type) are set to -1.

    -

    attrp is only filled if not NULL and if its size specified in attrsize is large enough. It should be at least as large as union hwloc_obj_attr_u.

    -
    Returns
    0 if a type was correctly identified, otherwise -1.
    -
    Note
    This function is guaranteed to match any string returned by hwloc_obj_type_string() or hwloc_obj_type_snprintf().
    -
    -This is an extended version of the now deprecated hwloc_obj_type_sscanf().
    - -
    -
    - -

    ◆ hwloc_type_sscanf_as_depth()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_type_sscanf_as_depth (const char * string,
    hwloc_obj_type_t * typep,
    hwloc_topology_t topology,
    int * depthp 
    )
    -
    - -

    Return an object type and its level depth from a type string.

    -

    Convert strings such as "Package" or "L1iCache" into the corresponding types and return in depthp the depth of the corresponding level in the topology topology.

    -

    If no object of this type is present on the underlying architecture, HWLOC_TYPE_DEPTH_UNKNOWN is returned.

    -

    If multiple such levels exist (for instance if giving Group without any depth), the function may return HWLOC_TYPE_DEPTH_MULTIPLE instead.

    -

    The matched object type is set in typep if typep is non NULL.

    -
    Note
    This function is similar to hwloc_type_sscanf() followed by hwloc_get_type_depth() but it also automatically disambiguates multiple group levels etc.
    -
    -This function is guaranteed to match any string returned by hwloc_obj_type_string() or hwloc_obj_type_snprintf().
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    -
    Consulting and Adding Key-Value Info Attributes
    -
    -
    - - - - - - -

    -Functions

    static const char * hwloc_obj_get_info_by_name (hwloc_obj_t obj, const char *name)
     
    int hwloc_obj_add_info (hwloc_obj_t obj, const char *name, const char *value)
     
    -

    Detailed Description

    -

    Function Documentation

    - -

    ◆ hwloc_obj_add_info()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_obj_add_info (hwloc_obj_t obj,
    const char * name,
    const char * value 
    )
    -
    - -

    Add the given info name and value pair to the given object.

    -

    The info is appended to the existing info array even if another key with the same name already exists.

    -

    The input strings are copied before being added in the object infos.

    -
    Returns
    0 on success, -1 on error.
    -
    Note
    This function may be used to enforce object colors in the lstopo graphical output by using "lstopoStyle" as a name and "Background=#rrggbb" as a value. See CUSTOM COLORS in the lstopo(1) manpage for details.
    -
    -If value contains some non-printable characters, they will be dropped when exporting to XML, see hwloc_topology_export_xml() in hwloc/export.h.
    - -
    -
    - -

    ◆ hwloc_obj_get_info_by_name()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static const char* hwloc_obj_get_info_by_name (hwloc_obj_t obj,
    const char * name 
    )
    -     		-inlinestatic
    -
    - -

    Search the given key name in object infos and return the corresponding value.

    -

    If multiple keys match the given name, only the first one is returned.

    -
    Returns
    NULL if no such key exists.
    - -
    -
    -
    - - - - - - - -
    -
    -Enumerations | -Functions
    -
    -
    CPU binding
    -
    -
    - - - - -

    -Enumerations

    enum  hwloc_cpubind_flags_t { HWLOC_CPUBIND_PROCESS -, HWLOC_CPUBIND_THREAD -, HWLOC_CPUBIND_STRICT -, HWLOC_CPUBIND_NOMEMBIND - }
     
    - - - - - - - - - - - - - - - - - -

    -Functions

    int hwloc_set_cpubind (hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags)
     
    int hwloc_get_cpubind (hwloc_topology_t topology, hwloc_cpuset_t set, int flags)
     
    int hwloc_set_proc_cpubind (hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_cpuset_t set, int flags)
     
    int hwloc_get_proc_cpubind (hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags)
     
    int hwloc_set_thread_cpubind (hwloc_topology_t topology, hwloc_thread_t thread, hwloc_const_cpuset_t set, int flags)
     
    int hwloc_get_thread_cpubind (hwloc_topology_t topology, hwloc_thread_t thread, hwloc_cpuset_t set, int flags)
     
    int hwloc_get_last_cpu_location (hwloc_topology_t topology, hwloc_cpuset_t set, int flags)
     
    int hwloc_get_proc_last_cpu_location (hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags)
     
    -

    Detailed Description

    -

    Some operating systems only support binding threads or processes to a single PU. Others allow binding to larger sets such as entire Cores or Packages or even random sets of individual PUs. In such operating system, the scheduler is free to run the task on one of these PU, then migrate it to another PU, etc. It is often useful to call hwloc_bitmap_singlify() on the target CPU set before passing it to the binding function to avoid these expensive migrations. See the documentation of hwloc_bitmap_singlify() for details.

    -

    Some operating systems do not provide all hwloc-supported mechanisms to bind processes, threads, etc. hwloc_topology_get_support() may be used to query about the actual CPU binding support in the currently used operating system.

    -

    When the requested binding operation is not available and the HWLOC_CPUBIND_STRICT flag was passed, the function returns -1. errno is set to ENOSYS when it is not possible to bind the requested kind of object processes/threads. errno is set to EXDEV when the requested cpuset can not be enforced (e.g. some systems only allow one CPU, and some other systems only allow one NUMA node).

    -

    If HWLOC_CPUBIND_STRICT was not passed, the function may fail as well, or the operating system may use a slightly different operation (with side-effects, smaller binding set, etc.) when the requested operation is not exactly supported.

    -

    The most portable version that should be preferred over the others, whenever possible, is the following one which just binds the current program, assuming it is single-threaded:

    -
    hwloc_set_cpubind(topology, set, 0),
    -
    hwloc_set_cpubind
    int hwloc_set_cpubind(hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags)
    Bind current process or thread on CPUs given in physical bitmap set.
    -

    If the program may be multithreaded, the following one should be preferred to only bind the current thread:

    -
    hwloc_set_cpubind(topology, set, HWLOC_CPUBIND_THREAD),
    -
    HWLOC_CPUBIND_THREAD
    @ HWLOC_CPUBIND_THREAD
    Bind current thread of current process.
    Definition: hwloc.h:1162
    -
    See also
    Some example codes are available under doc/examples/ in the source tree.
    -
    Note
    To unbind, just call the binding function with either a full cpuset or a cpuset equal to the system cpuset.
    -
    -On some operating systems, CPU binding may have effects on memory binding, see HWLOC_CPUBIND_NOMEMBIND
    -
    -Running lstopo --top or hwloc-ps can be a very convenient tool to check how binding actually happened.
    -

    Enumeration Type Documentation

    - -

    ◆ hwloc_cpubind_flags_t

    - -
    -
    - - - - -
    enum hwloc_cpubind_flags_t
    -
    - -

    Process/Thread binding flags.

    -

    These bit flags can be used to refine the binding policy.

    -

    The default (0) is to bind the current process, assumed to be single-threaded, in a non-strict way. This is the most portable way to bind as all operating systems usually provide it.

    -
    Note
    Not all systems support all kinds of binding. See the "Detailed Description" section of CPU binding for a description of errors that can occur.
    - - - - - -
    Enumerator
    HWLOC_CPUBIND_PROCESS 

    Bind all threads of the current (possibly) multithreaded process.

    -
    HWLOC_CPUBIND_THREAD 

    Bind current thread of current process.

    -
    HWLOC_CPUBIND_STRICT 

    Request for strict binding from the OS.

    -

    By default, when the designated CPUs are all busy while other CPUs are idle, operating systems may execute the thread/process on those other CPUs instead of the designated CPUs, to let them progress anyway. Strict binding means that the thread/process will _never_ execute on other CPUs than the designated CPUs, even when those are busy with other tasks and other CPUs are idle.

    -
    Note
    Depending on the operating system, strict binding may not be possible (e.g., the OS does not implement it) or not allowed (e.g., for an administrative reasons), and the function will fail in that case.
    -

    When retrieving the binding of a process, this flag checks whether all its threads actually have the same binding. If the flag is not given, the binding of each thread will be accumulated.

    -
    Note
    This flag is meaningless when retrieving the binding of a thread.
    -
    HWLOC_CPUBIND_NOMEMBIND 

    Avoid any effect on memory binding.

    -

    On some operating systems, some CPU binding function would also bind the memory on the corresponding NUMA node. It is often not a problem for the application, but if it is, setting this flag will make hwloc avoid using OS functions that would also bind memory. This will however reduce the support of CPU bindings, i.e. potentially return -1 with errno set to ENOSYS in some cases.

    -

    This flag is only meaningful when used with functions that set the CPU binding. It is ignored when used with functions that get CPU binding information.

    -
    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_get_cpubind()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_get_cpubind (hwloc_topology_t topology,
    hwloc_cpuset_t set,
    int flags 
    )
    -
    - -

    Get current process or thread binding.

    -

    The CPU-set set (previously allocated by the caller) is filled with the list of PUs which the process or thread (according to flags) was last bound to.

    - -
    -
    - -

    ◆ hwloc_get_last_cpu_location()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_get_last_cpu_location (hwloc_topology_t topology,
    hwloc_cpuset_t set,
    int flags 
    )
    -
    - -

    Get the last physical CPU where the current process or thread ran.

    -

    The CPU-set set (previously allocated by the caller) is filled with the list of PUs which the process or thread (according to flags) last ran on.

    -

    The operating system may move some tasks from one processor to another at any time according to their binding, so this function may return something that is already outdated.

    -

    flags can include either HWLOC_CPUBIND_PROCESS or HWLOC_CPUBIND_THREAD to specify whether the query should be for the whole process (union of all CPUs on which all threads are running), or only the current thread. If the process is single-threaded, flags can be set to zero to let hwloc use whichever method is available on the underlying OS.

    - -
    -
    - -

    ◆ hwloc_get_proc_cpubind()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_get_proc_cpubind (hwloc_topology_t topology,
    hwloc_pid_t pid,
    hwloc_cpuset_t set,
    int flags 
    )
    -
    - -

    Get the current physical binding of process pid.

    -

    The CPU-set set (previously allocated by the caller) is filled with the list of PUs which the process was last bound to.

    -
    Note
    hwloc_pid_t is pid_t on Unix platforms, and HANDLE on native Windows platforms.
    -
    -As a special case on Linux, if a tid (thread ID) is supplied instead of a pid (process ID) and HWLOC_CPUBIND_THREAD is passed in flags, the binding for that specific thread is returned.
    -
    -On non-Linux systems, HWLOC_CPUBIND_THREAD can not be used in flags.
    - -
    -
    - -

    ◆ hwloc_get_proc_last_cpu_location()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_get_proc_last_cpu_location (hwloc_topology_t topology,
    hwloc_pid_t pid,
    hwloc_cpuset_t set,
    int flags 
    )
    -
    - -

    Get the last physical CPU where a process ran.

    -

    The CPU-set set (previously allocated by the caller) is filled with the list of PUs which the process last ran on.

    -

    The operating system may move some tasks from one processor to another at any time according to their binding, so this function may return something that is already outdated.

    -
    Note
    hwloc_pid_t is pid_t on Unix platforms, and HANDLE on native Windows platforms.
    -
    -As a special case on Linux, if a tid (thread ID) is supplied instead of a pid (process ID) and HWLOC_CPUBIND_THREAD is passed in flags, the last CPU location of that specific thread is returned.
    -
    -On non-Linux systems, HWLOC_CPUBIND_THREAD can not be used in flags.
    - -
    -
    - -

    ◆ hwloc_get_thread_cpubind()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_get_thread_cpubind (hwloc_topology_t topology,
    hwloc_thread_t thread,
    hwloc_cpuset_t set,
    int flags 
    )
    -
    - -

    Get the current physical binding of thread tid.

    -

    The CPU-set set (previously allocated by the caller) is filled with the list of PUs which the thread was last bound to.

    -
    Note
    hwloc_thread_t is pthread_t on Unix platforms, and HANDLE on native Windows platforms.
    -
    -HWLOC_CPUBIND_PROCESS can not be used in flags.
    - -
    -
    - -

    ◆ hwloc_set_cpubind()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_set_cpubind (hwloc_topology_t topology,
    hwloc_const_cpuset_t set,
    int flags 
    )
    -
    - -

    Bind current process or thread on CPUs given in physical bitmap set.

    -
    Returns
    -1 with errno set to ENOSYS if the action is not supported
    -
    --1 with errno set to EXDEV if the binding cannot be enforced
    - -
    -
    - -

    ◆ hwloc_set_proc_cpubind()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_set_proc_cpubind (hwloc_topology_t topology,
    hwloc_pid_t pid,
    hwloc_const_cpuset_t set,
    int flags 
    )
    -
    - -

    Bind a process pid on CPUs given in physical bitmap set.

    -
    Note
    hwloc_pid_t is pid_t on Unix platforms, and HANDLE on native Windows platforms.
    -
    -As a special case on Linux, if a tid (thread ID) is supplied instead of a pid (process ID) and HWLOC_CPUBIND_THREAD is passed in flags, the binding is applied to that specific thread.
    -
    -On non-Linux systems, HWLOC_CPUBIND_THREAD can not be used in flags.
    - -
    -
    - -

    ◆ hwloc_set_thread_cpubind()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_set_thread_cpubind (hwloc_topology_t topology,
    hwloc_thread_t thread,
    hwloc_const_cpuset_t set,
    int flags 
    )
    -
    - -

    Bind a thread thread on CPUs given in physical bitmap set.

    -
    Note
    hwloc_thread_t is pthread_t on Unix platforms, and HANDLE on native Windows platforms.
    -
    -HWLOC_CPUBIND_PROCESS can not be used in flags.
    - -
    -
    -
    - - - - - - - -
    -
    -Enumerations | -Functions
    -
    -
    Memory binding
    -
    -
    - - - - - - -

    -Enumerations

    enum  hwloc_membind_policy_t {
    -  HWLOC_MEMBIND_DEFAULT -, HWLOC_MEMBIND_FIRSTTOUCH -, HWLOC_MEMBIND_BIND -, HWLOC_MEMBIND_INTERLEAVE -,
    -  HWLOC_MEMBIND_NEXTTOUCH -, HWLOC_MEMBIND_MIXED -
    - }
     
    enum  hwloc_membind_flags_t {
    -  HWLOC_MEMBIND_PROCESS -, HWLOC_MEMBIND_THREAD -, HWLOC_MEMBIND_STRICT -, HWLOC_MEMBIND_MIGRATE -,
    -  HWLOC_MEMBIND_NOCPUBIND -, HWLOC_MEMBIND_BYNODESET -
    - }
     
    - - - - - - - - - - - - - - - - - - - - - - - -

    -Functions

    int hwloc_set_membind (hwloc_topology_t topology, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags)
     
    int hwloc_get_membind (hwloc_topology_t topology, hwloc_bitmap_t set, hwloc_membind_policy_t *policy, int flags)
     
    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)
     
    int hwloc_get_proc_membind (hwloc_topology_t topology, hwloc_pid_t pid, hwloc_bitmap_t set, hwloc_membind_policy_t *policy, int flags)
     
    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)
     
    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)
     
    int hwloc_get_area_memlocation (hwloc_topology_t topology, const void *addr, size_t len, hwloc_bitmap_t set, int flags)
     
    void * hwloc_alloc (hwloc_topology_t topology, size_t len)
     
    void * hwloc_alloc_membind (hwloc_topology_t topology, size_t len, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags)
     
    static void * hwloc_alloc_membind_policy (hwloc_topology_t topology, size_t len, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags)
     
    int hwloc_free (hwloc_topology_t topology, void *addr, size_t len)
     
    -

    Detailed Description

    -

    Memory binding can be done three ways:

    - -

    Not all operating systems support all three ways. hwloc_topology_get_support() may be used to query about the actual memory binding support in the currently used operating system.

    -

    When the requested binding operation is not available and the HWLOC_MEMBIND_STRICT flag was passed, the function returns -1. errno will be set to ENOSYS when the system does support the specified action or policy (e.g., some systems only allow binding memory on a per-thread basis, whereas other systems only allow binding memory for all threads in a process). errno will be set to EXDEV when the requested set can not be enforced (e.g., some systems only allow binding memory to a single NUMA node).

    -

    If HWLOC_MEMBIND_STRICT was not passed, the function may fail as well, or the operating system may use a slightly different operation (with side-effects, smaller binding set, etc.) when the requested operation is not exactly supported.

    -

    The most portable form that should be preferred over the others whenever possible is as follows. It allocates some memory hopefully bound to the specified set. To do so, hwloc will possibly have to change the current memory binding policy in order to actually get the memory bound, if the OS does not provide any other way to simply allocate bound memory without changing the policy for all allocations. That is the difference with hwloc_alloc_membind(), which will never change the current memory binding policy.

    -
    hwloc_alloc_membind_policy(topology, size, set,
    -
    HWLOC_MEMBIND_BIND, 0);
    -
    hwloc_alloc_membind_policy
    static void * hwloc_alloc_membind_policy(hwloc_topology_t topology, size_t len, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags)
    Allocate some memory on NUMA memory nodes specified by set.
    -
    HWLOC_MEMBIND_BIND
    @ HWLOC_MEMBIND_BIND
    Allocate memory on the specified nodes.
    Definition: hwloc.h:1421
    -

    Each hwloc memory binding function takes a bitmap argument that is a CPU set by default, or a NUMA memory node set if the flag HWLOC_MEMBIND_BYNODESET is specified. See Object Sets (hwloc_cpuset_t and hwloc_nodeset_t) and The bitmap API for a discussion of CPU sets and NUMA memory node sets. It is also possible to convert between CPU set and node set using hwloc_cpuset_to_nodeset() or hwloc_cpuset_from_nodeset().

    -

    Memory binding by CPU set cannot work for CPU-less NUMA memory nodes. Binding by nodeset should therefore be preferred whenever possible.

    -
    See also
    Some example codes are available under doc/examples/ in the source tree.
    -
    Note
    On some operating systems, memory binding affects the CPU binding; see HWLOC_MEMBIND_NOCPUBIND
    -

    Enumeration Type Documentation

    - -

    ◆ hwloc_membind_flags_t

    - -
    -
    - - - - -
    enum hwloc_membind_flags_t
    -
    - -

    Memory binding flags.

    -

    These flags can be used to refine the binding policy. All flags can be logically OR'ed together with the exception of HWLOC_MEMBIND_PROCESS and HWLOC_MEMBIND_THREAD; these two flags are mutually exclusive.

    -

    Not all systems support all kinds of binding. hwloc_topology_get_support() may be used to query about the actual memory binding support in the currently used operating system. See the "Detailed Description" section of Memory binding for a description of errors that can occur.

    - - - - - - - -
    Enumerator
    HWLOC_MEMBIND_PROCESS 

    Set policy for all threads of the specified (possibly multithreaded) process. This flag is mutually exclusive with HWLOC_MEMBIND_THREAD.

    -
    HWLOC_MEMBIND_THREAD 

    Set policy for a specific thread of the current process. This flag is mutually exclusive with HWLOC_MEMBIND_PROCESS.

    -
    HWLOC_MEMBIND_STRICT 

    Request strict binding from the OS. The function will fail if the binding can not be guaranteed / completely enforced.

    -

    This flag has slightly different meanings depending on which function it is used with.

    -
    HWLOC_MEMBIND_MIGRATE 

    Migrate existing allocated memory. If the memory cannot be migrated and the HWLOC_MEMBIND_STRICT flag is passed, an error will be returned.

    -
    HWLOC_MEMBIND_NOCPUBIND 

    Avoid any effect on CPU binding.

    -

    On some operating systems, some underlying memory binding functions also bind the application to the corresponding CPU(s). Using this flag will cause hwloc to avoid using OS functions that could potentially affect CPU bindings. Note, however, that using NOCPUBIND may reduce hwloc's overall memory binding support. Specifically: some of hwloc's memory binding functions may fail with errno set to ENOSYS when used with NOCPUBIND.

    -
    HWLOC_MEMBIND_BYNODESET 

    Consider the bitmap argument as a nodeset.

    -

    The bitmap argument is considered a nodeset if this flag is given, or a cpuset otherwise by default.

    -

    Memory binding by CPU set cannot work for CPU-less NUMA memory nodes. Binding by nodeset should therefore be preferred whenever possible.

    -
    - -
    -
    - -

    ◆ hwloc_membind_policy_t

    - -
    -
    - - - - -
    enum hwloc_membind_policy_t
    -
    - -

    Memory binding policy.

    -

    These constants can be used to choose the binding policy. Only one policy can be used at a time (i.e., the values cannot be OR'ed together).

    -

    Not all systems support all kinds of binding. hwloc_topology_get_support() may be used to query about the actual memory binding policy support in the currently used operating system. See the "Detailed Description" section of Memory binding for a description of errors that can occur.

    - - - - - - - -
    Enumerator
    HWLOC_MEMBIND_DEFAULT 

    Reset the memory allocation policy to the system default. Depending on the operating system, this may correspond to HWLOC_MEMBIND_FIRSTTOUCH (Linux, FreeBSD), or HWLOC_MEMBIND_BIND (AIX, HP-UX, Solaris, Windows). This policy is never returned by get membind functions. The nodeset argument is ignored.

    -
    HWLOC_MEMBIND_FIRSTTOUCH 

    Allocate each memory page individually on the local NUMA node of the thread that touches it.

    -

    The given nodeset should usually be hwloc_topology_get_topology_nodeset() so that the touching thread may run and allocate on any node in the system.

    -

    On AIX, if the nodeset is smaller, pages are allocated locally (if the local node is in the nodeset) or from a random non-local node (otherwise).

    -
    HWLOC_MEMBIND_BIND 

    Allocate memory on the specified nodes.

    -
    HWLOC_MEMBIND_INTERLEAVE 

    Allocate memory on the given nodes in an interleaved / round-robin manner. The precise layout of the memory across multiple NUMA nodes is OS/system specific. Interleaving can be useful when threads distributed across the specified NUMA nodes will all be accessing the whole memory range concurrently, since the interleave will then balance the memory references.

    -
    HWLOC_MEMBIND_NEXTTOUCH 

    For each page bound with this policy, by next time it is touched (and next time only), it is moved from its current location to the local NUMA node of the thread where the memory reference occurred (if it needs to be moved at all).

    -
    HWLOC_MEMBIND_MIXED 

    Returned by get_membind() functions when multiple threads or parts of a memory area have differing memory binding policies. Also returned when binding is unknown because binding hooks are empty when the topology is loaded from XML without HWLOC_THISSYSTEM=1, etc.

    -
    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_alloc()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    void* hwloc_alloc (hwloc_topology_t topology,
    size_t len 
    )
    -
    - -

    Allocate some memory.

    -

    This is equivalent to malloc(), except that it tries to allocate page-aligned memory from the OS.

    -
    Note
    The allocated memory should be freed with hwloc_free().
    - -
    -
    - -

    ◆ hwloc_alloc_membind()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    void* hwloc_alloc_membind (hwloc_topology_t topology,
    size_t len,
    hwloc_const_bitmap_t set,
    hwloc_membind_policy_t policy,
    int flags 
    )
    -
    - -

    Allocate some memory on NUMA memory nodes specified by set.

    -
    Returns
    NULL with errno set to ENOSYS if the action is not supported and HWLOC_MEMBIND_STRICT is given
    -
    -NULL with errno set to EXDEV if the binding cannot be enforced and HWLOC_MEMBIND_STRICT is given
    -
    -NULL with errno set to ENOMEM if the memory allocation failed even before trying to bind.
    -

    If HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset. Otherwise it's a cpuset.

    -
    Note
    The allocated memory should be freed with hwloc_free().
    - -
    -
    - -

    ◆ hwloc_alloc_membind_policy()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static void* hwloc_alloc_membind_policy (hwloc_topology_t topology,
    size_t len,
    hwloc_const_bitmap_t set,
    hwloc_membind_policy_t policy,
    int flags 
    )
    -     		-inlinestatic
    -
    - -

    Allocate some memory on NUMA memory nodes specified by set.

    -

    First, try to allocate properly with hwloc_alloc_membind(). On failure, the current process or thread memory binding policy is changed with hwloc_set_membind() before allocating memory. Thus this function works in more cases, at the expense of changing the current state (possibly affecting future allocations that would not specify any policy).

    -

    If HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset. Otherwise it's a cpuset.

    - -
    -
    - -

    ◆ hwloc_free()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_free (hwloc_topology_t topology,
    void * addr,
    size_t len 
    )
    -
    - -

    Free memory that was previously allocated by hwloc_alloc() or hwloc_alloc_membind().

    - -
    -
    - -

    ◆ hwloc_get_area_membind()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    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 
    )
    -
    - -

    Query the CPUs near the physical NUMA node(s) and binding policy of the memory identified by (addr, len ).

    -

    The bitmap set (previously allocated by the caller) is filled with the memory area binding.

    -

    This function has two output parameters: set and policy. The values returned in these parameters depend on both the flags passed in and the memory binding policies and nodesets of the pages in the address range.

    -

    If HWLOC_MEMBIND_STRICT is specified, the target pages are first checked to see if they all have the same memory binding policy and nodeset. If they do not, -1 is returned and errno is set to EXDEV. If they are identical across all pages, the set and policy are returned in set and policy, respectively.

    -

    If HWLOC_MEMBIND_STRICT is not specified, the union of all NUMA node(s) containing pages in the address range is calculated. If all pages in the target have the same policy, it is returned in policy. Otherwise, policy is set to HWLOC_MEMBIND_MIXED.

    -

    If HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset. Otherwise it's a cpuset.

    -

    If any other flags are specified, -1 is returned and errno is set to EINVAL.

    -

    If len is 0, -1 is returned and errno is set to EINVAL.

    - -
    -
    - -

    ◆ hwloc_get_area_memlocation()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_get_area_memlocation (hwloc_topology_t topology,
    const void * addr,
    size_t len,
    hwloc_bitmap_t set,
    int flags 
    )
    -
    - -

    Get the NUMA nodes where memory identified by (addr, len ) is physically allocated.

    -

    The bitmap set (previously allocated by the caller) is filled according to the NUMA nodes where the memory area pages are physically allocated. If no page is actually allocated yet, set may be empty.

    -

    If pages spread to multiple nodes, it is not specified whether they spread equitably, or whether most of them are on a single node, etc.

    -

    The operating system may move memory pages from one processor to another at any time according to their binding, so this function may return something that is already outdated.

    -

    If HWLOC_MEMBIND_BYNODESET is specified in flags, set is considered a nodeset. Otherwise it's a cpuset.

    -

    If len is 0, set is emptied.

    - -
    -
    - -

    ◆ hwloc_get_membind()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_get_membind (hwloc_topology_t topology,
    hwloc_bitmap_t set,
    hwloc_membind_policy_t * policy,
    int flags 
    )
    -
    - -

    Query the default memory binding policy and physical locality of the current process or thread.

    -

    The bitmap set (previously allocated by the caller) is filled with the process or thread memory binding.

    -

    This function has two output parameters: set and policy. The values returned in these parameters depend on both the flags passed in and the current memory binding policies and nodesets in the queried target.

    -

    Passing the HWLOC_MEMBIND_PROCESS flag specifies that the query target is the current policies and nodesets for all the threads in the current process. Passing HWLOC_MEMBIND_THREAD specifies that the query target is the current policy and nodeset for only the thread invoking this function.

    -

    If neither of these flags are passed (which is the most portable method), the process is assumed to be single threaded. This allows hwloc to use either process-based OS functions or thread-based OS functions, depending on which are available.

    -

    HWLOC_MEMBIND_STRICT is only meaningful when HWLOC_MEMBIND_PROCESS is also specified. In this case, hwloc will check the default memory policies and nodesets for all threads in the process. If they are not identical, -1 is returned and errno is set to EXDEV. If they are identical, the values are returned in set and policy.

    -

    Otherwise, if HWLOC_MEMBIND_PROCESS is specified (and HWLOC_MEMBIND_STRICT is not specified), the default set from each thread is logically OR'ed together. If all threads' default policies are the same, policy is set to that policy. If they are different, policy is set to HWLOC_MEMBIND_MIXED.

    -

    In the HWLOC_MEMBIND_THREAD case (or when neither HWLOC_MEMBIND_PROCESS or HWLOC_MEMBIND_THREAD is specified), there is only one set and policy; they are returned in set and policy, respectively.

    -

    If HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset. Otherwise it's a cpuset.

    -

    If any other flags are specified, -1 is returned and errno is set to EINVAL.

    - -
    -
    - -

    ◆ hwloc_get_proc_membind()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_get_proc_membind (hwloc_topology_t topology,
    hwloc_pid_t pid,
    hwloc_bitmap_t set,
    hwloc_membind_policy_t * policy,
    int flags 
    )
    -
    - -

    Query the default memory binding policy and physical locality of the specified process.

    -

    The bitmap set (previously allocated by the caller) is filled with the process memory binding.

    -

    This function has two output parameters: set and policy. The values returned in these parameters depend on both the flags passed in and the current memory binding policies and nodesets in the queried target.

    -

    Passing the HWLOC_MEMBIND_PROCESS flag specifies that the query target is the current policies and nodesets for all the threads in the specified process. If HWLOC_MEMBIND_PROCESS is not specified (which is the most portable method), the process is assumed to be single threaded. This allows hwloc to use either process-based OS functions or thread-based OS functions, depending on which are available.

    -

    Note that it does not make sense to pass HWLOC_MEMBIND_THREAD to this function.

    -

    If HWLOC_MEMBIND_STRICT is specified, hwloc will check the default memory policies and nodesets for all threads in the specified process. If they are not identical, -1 is returned and errno is set to EXDEV. If they are identical, the values are returned in set and policy.

    -

    Otherwise, set is set to the logical OR of all threads' default set. If all threads' default policies are the same, policy is set to that policy. If they are different, policy is set to HWLOC_MEMBIND_MIXED.

    -

    If HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset. Otherwise it's a cpuset.

    -

    If any other flags are specified, -1 is returned and errno is set to EINVAL.

    -
    Note
    hwloc_pid_t is pid_t on Unix platforms, and HANDLE on native Windows platforms.
    - -
    -
    - -

    ◆ hwloc_set_area_membind()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    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 
    )
    -
    - -

    Bind the already-allocated memory identified by (addr, len) to the NUMA node(s) specified by set.

    -

    If HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset. Otherwise it's a cpuset.

    -
    Returns
    0 if len is 0.
    -
    --1 with errno set to ENOSYS if the action is not supported
    -
    --1 with errno set to EXDEV if the binding cannot be enforced
    - -
    -
    - -

    ◆ hwloc_set_membind()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_set_membind (hwloc_topology_t topology,
    hwloc_const_bitmap_t set,
    hwloc_membind_policy_t policy,
    int flags 
    )
    -
    - -

    Set the default memory binding policy of the current process or thread to prefer the NUMA node(s) specified by set.

    -

    If neither HWLOC_MEMBIND_PROCESS nor HWLOC_MEMBIND_THREAD is specified, the current process is assumed to be single-threaded. This is the most portable form as it permits hwloc to use either process-based OS functions or thread-based OS functions, depending on which are available.

    -

    If HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset. Otherwise it's a cpuset.

    -
    Returns
    -1 with errno set to ENOSYS if the action is not supported
    -
    --1 with errno set to EXDEV if the binding cannot be enforced
    - -
    -
    - -

    ◆ hwloc_set_proc_membind()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    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 
    )
    -
    - -

    Set the default memory binding policy of the specified process to prefer the NUMA node(s) specified by set.

    -

    If HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset. Otherwise it's a cpuset.

    -
    Returns
    -1 with errno set to ENOSYS if the action is not supported
    -
    --1 with errno set to EXDEV if the binding cannot be enforced
    -
    Note
    hwloc_pid_t is pid_t on Unix platforms, and HANDLE on native Windows platforms.
    - -
    -
    -
    - - - - - - - -
    -
    -Enumerations | -Functions
    -
    -
    Changing the Source of Topology Discovery
    -
    -
    - - - - -

    -Enumerations

    enum  hwloc_topology_components_flag_e { HWLOC_TOPOLOGY_COMPONENTS_FLAG_BLACKLIST - }
     
    - - - - - - - - - - - -

    -Functions

    int hwloc_topology_set_pid (hwloc_topology_t restrict topology, hwloc_pid_t pid)
     
    int hwloc_topology_set_synthetic (hwloc_topology_t restrict topology, const char *restrict description)
     
    int hwloc_topology_set_xml (hwloc_topology_t restrict topology, const char *restrict xmlpath)
     
    int hwloc_topology_set_xmlbuffer (hwloc_topology_t restrict topology, const char *restrict buffer, int size)
     
    int hwloc_topology_set_components (hwloc_topology_t restrict topology, unsigned long flags, const char *restrict name)
     
    -

    Detailed Description

    -

    If none of the functions below is called, the default is to detect all the objects of the machine that the caller is allowed to access.

    -

    This default behavior may also be modified through environment variables if the application did not modify it already. Setting HWLOC_XMLFILE in the environment enforces the discovery from a XML file as if hwloc_topology_set_xml() had been called. Setting HWLOC_SYNTHETIC enforces a synthetic topology as if hwloc_topology_set_synthetic() had been called.

    -

    Finally, HWLOC_THISSYSTEM enforces the return value of hwloc_topology_is_thissystem().

    -

    Enumeration Type Documentation

    - -

    ◆ hwloc_topology_components_flag_e

    - -
    -
    - - - - -
    enum hwloc_topology_components_flag_e
    -
    - -

    Flags to be passed to hwloc_topology_set_components()

    - - -
    Enumerator
    HWLOC_TOPOLOGY_COMPONENTS_FLAG_BLACKLIST 

    Blacklist the target component from being used.

    -
    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_topology_set_components()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_set_components (hwloc_topology_t restrict topology,
    unsigned long flags,
    const char *restrict name 
    )
    -
    - -

    Prevent a discovery component from being used for a topology.

    -

    name is the name of the discovery component that should not be used when loading topology topology. The name is a string such as "cuda".

    -

    For components with multiple phases, it may also be suffixed with the name of a phase, for instance "linux:io".

    -

    flags should be HWLOC_TOPOLOGY_COMPONENTS_FLAG_BLACKLIST.

    -

    This may be used to avoid expensive parts of the discovery process. For instance, CUDA-specific discovery may be expensive and unneeded while generic I/O discovery could still be useful.

    - -
    -
    - -

    ◆ hwloc_topology_set_pid()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_set_pid (hwloc_topology_t restrict topology,
    hwloc_pid_t pid 
    )
    -
    - -

    Change which process the topology is viewed from.

    -

    On some systems, processes may have different views of the machine, for instance the set of allowed CPUs. By default, hwloc exposes the view from the current process. Calling hwloc_topology_set_pid() permits to make it expose the topology of the machine from the point of view of another process.

    -
    Note
    hwloc_pid_t is pid_t on Unix platforms, and HANDLE on native Windows platforms.
    -
    --1 is returned and errno is set to ENOSYS on platforms that do not support this feature.
    - -
    -
    - -

    ◆ hwloc_topology_set_synthetic()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_set_synthetic (hwloc_topology_t restrict topology,
    const char *restrict description 
    )
    -
    - -

    Enable synthetic topology.

    -

    Gather topology information from the given description, a space-separated string of <type:number> describing the object type and arity at each level. All types may be omitted (space-separated string of numbers) so that hwloc chooses all types according to usual topologies. See also the Synthetic topologies.

    -

    Setting the environment variable HWLOC_SYNTHETIC may also result in this behavior.

    -

    If description was properly parsed and describes a valid topology configuration, this function returns 0. Otherwise -1 is returned and errno is set to EINVAL.

    -

    Note that this function does not actually load topology information; it just tells hwloc where to load it from. You'll still need to invoke hwloc_topology_load() to actually load the topology information.

    -
    Note
    For convenience, this backend provides empty binding hooks which just return success.
    -
    -On success, the synthetic component replaces the previously enabled component (if any), but the topology is not actually modified until hwloc_topology_load().
    - -
    -
    - -

    ◆ hwloc_topology_set_xml()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_set_xml (hwloc_topology_t restrict topology,
    const char *restrict xmlpath 
    )
    -
    - -

    Enable XML-file based topology.

    -

    Gather topology information from the XML file given at xmlpath. Setting the environment variable HWLOC_XMLFILE may also result in this behavior. This file may have been generated earlier with hwloc_topology_export_xml() in hwloc/export.h, or lstopo file.xml.

    -

    Note that this function does not actually load topology information; it just tells hwloc where to load it from. You'll still need to invoke hwloc_topology_load() to actually load the topology information.

    -
    Returns
    -1 with errno set to EINVAL on failure to read the XML file.
    -
    Note
    See also hwloc_topology_set_userdata_import_callback() for importing application-specific object userdata.
    -
    -For convenience, this backend provides empty binding hooks which just return success. To have hwloc still actually call OS-specific hooks, the HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM has to be set to assert that the loaded file is really the underlying system.
    -
    -On success, the XML component replaces the previously enabled component (if any), but the topology is not actually modified until hwloc_topology_load().
    - -
    -
    - -

    ◆ hwloc_topology_set_xmlbuffer()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_set_xmlbuffer (hwloc_topology_t restrict topology,
    const char *restrict buffer,
    int size 
    )
    -
    - -

    Enable XML based topology using a memory buffer (instead of a file, as with hwloc_topology_set_xml()).

    -

    Gather topology information from the XML memory buffer given at buffer and of length size. This buffer may have been filled earlier with hwloc_topology_export_xmlbuffer() in hwloc/export.h.

    -

    Note that this function does not actually load topology information; it just tells hwloc where to load it from. You'll still need to invoke hwloc_topology_load() to actually load the topology information.

    -
    Returns
    -1 with errno set to EINVAL on failure to read the XML buffer.
    -
    Note
    See also hwloc_topology_set_userdata_import_callback() for importing application-specific object userdata.
    -
    -For convenience, this backend provides empty binding hooks which just return success. To have hwloc still actually call OS-specific hooks, the HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM has to be set to assert that the loaded file is really the underlying system.
    -
    -On success, the XML component replaces the previously enabled component (if any), but the topology is not actually modified until hwloc_topology_load().
    - -
    -
    -
    - - - - - - - -
    -
    -Data Structures | -Enumerations | -Functions
    -
    -
    Topology Detection Configuration and Query
    -
    -
    - - - - - - - - - - - - -

    -Data Structures

    struct  hwloc_topology_discovery_support
     
    struct  hwloc_topology_cpubind_support
     
    struct  hwloc_topology_membind_support
     
    struct  hwloc_topology_misc_support
     
    struct  hwloc_topology_support
     
    - - - - - -

    -Enumerations

    enum  hwloc_topology_flags_e {
    -  HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED -, HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM -, HWLOC_TOPOLOGY_FLAG_THISSYSTEM_ALLOWED_RESOURCES -, HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT = (1UL<<3) -,
    -  HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_CPUBINDING = (1UL<<4) -, HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_MEMBINDING = (1UL<<5) -, HWLOC_TOPOLOGY_FLAG_DONT_CHANGE_BINDING = (1UL<<6) -, HWLOC_TOPOLOGY_FLAG_NO_DISTANCES = (1UL<<7) -,
    -  HWLOC_TOPOLOGY_FLAG_NO_MEMATTRS = (1UL<<8) -, HWLOC_TOPOLOGY_FLAG_NO_CPUKINDS = (1UL<<9) -
    - }
     
    enum  hwloc_type_filter_e { HWLOC_TYPE_FILTER_KEEP_ALL -, HWLOC_TYPE_FILTER_KEEP_NONE -, HWLOC_TYPE_FILTER_KEEP_STRUCTURE -, HWLOC_TYPE_FILTER_KEEP_IMPORTANT - }
     
    - - - - - - - - - - - - - - - - - - - - - - - - - -

    -Functions

    int hwloc_topology_set_flags (hwloc_topology_t topology, unsigned long flags)
     
    unsigned long hwloc_topology_get_flags (hwloc_topology_t topology)
     
    int hwloc_topology_is_thissystem (hwloc_topology_t restrict topology)
     
    const struct hwloc_topology_support * hwloc_topology_get_support (hwloc_topology_t restrict topology)
     
    int hwloc_topology_set_type_filter (hwloc_topology_t topology, hwloc_obj_type_t type, enum hwloc_type_filter_e filter)
     
    int hwloc_topology_get_type_filter (hwloc_topology_t topology, hwloc_obj_type_t type, enum hwloc_type_filter_e *filter)
     
    int hwloc_topology_set_all_types_filter (hwloc_topology_t topology, enum hwloc_type_filter_e filter)
     
    int hwloc_topology_set_cache_types_filter (hwloc_topology_t topology, enum hwloc_type_filter_e filter)
     
    int hwloc_topology_set_icache_types_filter (hwloc_topology_t topology, enum hwloc_type_filter_e filter)
     
    int hwloc_topology_set_io_types_filter (hwloc_topology_t topology, enum hwloc_type_filter_e filter)
     
    void hwloc_topology_set_userdata (hwloc_topology_t topology, const void *userdata)
     
    void * hwloc_topology_get_userdata (hwloc_topology_t topology)
     
    -

    Detailed Description

    -

    Several functions can optionally be called between hwloc_topology_init() and hwloc_topology_load() to configure how the detection should be performed, e.g. to ignore some objects types, define a synthetic topology, etc.

    -

    Enumeration Type Documentation

    - -

    ◆ hwloc_topology_flags_e

    - -
    -
    - - - - -
    enum hwloc_topology_flags_e
    -
    - -

    Flags to be set onto a topology context before load.

    -

    Flags should be given to hwloc_topology_set_flags(). They may also be returned by hwloc_topology_get_flags().

    - - - - - - - - - - - -
    Enumerator
    HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED 

    Detect the whole system, ignore reservations, include disallowed objects.

    -

    Gather all online resources, even if some were disabled by the administrator. For instance, ignore Linux Cgroup/Cpusets and gather all processors and memory nodes. However offline PUs and NUMA nodes are still ignored.

    -

    When this flag is not set, PUs and NUMA nodes that are disallowed are not added to the topology. Parent objects (package, core, cache, etc.) are added only if some of their children are allowed. All existing PUs and NUMA nodes in the topology are allowed. hwloc_topology_get_allowed_cpuset() and hwloc_topology_get_allowed_nodeset() are equal to the root object cpuset and nodeset.

    -

    When this flag is set, the actual sets of allowed PUs and NUMA nodes are given by hwloc_topology_get_allowed_cpuset() and hwloc_topology_get_allowed_nodeset(). They may be smaller than the root object cpuset and nodeset.

    -

    If the current topology is exported to XML and reimported later, this flag should be set again in the reimported topology so that disallowed resources are reimported as well.

    -
    HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM 

    Assume that the selected backend provides the topology for the system on which we are running.

    -

    This forces hwloc_topology_is_thissystem() to return 1, i.e. makes hwloc assume that the selected backend provides the topology for the system on which we are running, even if it is not the OS-specific backend but the XML backend for instance. This means making the binding functions actually call the OS-specific system calls and really do binding, while the XML backend would otherwise provide empty hooks just returning success.

    -

    Setting the environment variable HWLOC_THISSYSTEM may also result in the same behavior.

    -

    This can be used for efficiency reasons to first detect the topology once, save it to an XML file, and quickly reload it later through the XML backend, but still having binding functions actually do bind.

    -
    HWLOC_TOPOLOGY_FLAG_THISSYSTEM_ALLOWED_RESOURCES 

    Get the set of allowed resources from the local operating system even if the topology was loaded from XML or synthetic description.

    -

    If the topology was loaded from XML or from a synthetic string, restrict it by applying the current process restrictions such as Linux Cgroup/Cpuset.

    -

    This is useful when the topology is not loaded directly from the local machine (e.g. for performance reason) and it comes with all resources, while the running process is restricted to only parts of the machine.

    -

    This flag is ignored unless HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM is also set since the loaded topology must match the underlying machine where restrictions will be gathered from.

    -

    Setting the environment variable HWLOC_THISSYSTEM_ALLOWED_RESOURCES would result in the same behavior.

    -
    HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT 

    Import support from the imported topology.

    -

    When importing a XML topology from a remote machine, binding is disabled by default (see HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM). This disabling is also marked by putting zeroes in the corresponding supported feature bits reported by hwloc_topology_get_support().

    -

    The flag HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT actually imports support bits from the remote machine. It also sets the flag imported_support in the struct hwloc_topology_misc_support array. If the imported XML did not contain any support information (exporter hwloc is too old), this flag is not set.

    -

    Note that these supported features are only relevant for the hwloc installation that actually exported the XML topology (it may vary with the operating system, or with how hwloc was compiled).

    -

    Note that setting this flag however does not enable binding for the locally imported hwloc topology, it only reports what the remote hwloc and machine support.

    -
    HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_CPUBINDING 

    Do not consider resources outside of the process CPU binding.

    -

    If the binding of the process is limited to a subset of cores, ignore the other cores during discovery.

    -

    The resulting topology is identical to what a call to hwloc_topology_restrict() would generate, but this flag also prevents hwloc from ever touching other resources during the discovery.

    -

    This flag especially tells the x86 backend to never temporarily rebind a thread on any excluded core. This is useful on Windows because such temporary rebinding can change the process binding. Another use-case is to avoid cores that would not be able to perform the hwloc discovery anytime soon because they are busy executing some high-priority real-time tasks.

    -

    If process CPU binding is not supported, the thread CPU binding is considered instead if supported, or the flag is ignored.

    -

    This flag requires HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM as well since binding support is required.

    -
    HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_MEMBINDING 

    Do not consider resources outside of the process memory binding.

    -

    If the binding of the process is limited to a subset of NUMA nodes, ignore the other NUMA nodes during discovery.

    -

    The resulting topology is identical to what a call to hwloc_topology_restrict() would generate, but this flag also prevents hwloc from ever touching other resources during the discovery.

    -

    This flag is meant to be used together with HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_CPUBINDING when both cores and NUMA nodes should be ignored outside of the process binding.

    -

    If process memory binding is not supported, the thread memory binding is considered instead if supported, or the flag is ignored.

    -

    This flag requires HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM as well since binding support is required.

    -
    HWLOC_TOPOLOGY_FLAG_DONT_CHANGE_BINDING 

    Do not ever modify the process or thread binding during discovery.

    -

    This flag disables all hwloc discovery steps that require a change of the process or thread binding. This currently only affects the x86 backend which gets entirely disabled.

    -

    This is useful when hwloc_topology_load() is called while the application also creates additional threads or modifies the binding.

    -

    This flag is also a strict way to make sure the process binding will not change to due thread binding changes on Windows (see HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_CPUBINDING).

    -
    HWLOC_TOPOLOGY_FLAG_NO_DISTANCES 

    Ignore distances.

    -

    Ignore distance information from the operating systems (and from XML) and hence do not use distances for grouping.

    -
    HWLOC_TOPOLOGY_FLAG_NO_MEMATTRS 

    Ignore memory attributes.

    -

    Ignore memory attribues from the operating systems (and from XML).

    -
    HWLOC_TOPOLOGY_FLAG_NO_CPUKINDS 

    Ignore CPU Kinds.

    -

    Ignore CPU kind information from the operating systems (and from XML).

    -
    - -
    -
    - -

    ◆ hwloc_type_filter_e

    - -
    -
    - - - - -
    enum hwloc_type_filter_e
    -
    - -

    Type filtering flags.

    -

    By default, most objects are kept (HWLOC_TYPE_FILTER_KEEP_ALL). Instruction caches, I/O and Misc objects are ignored by default (HWLOC_TYPE_FILTER_KEEP_NONE). Die and Group levels are ignored unless they bring structure (HWLOC_TYPE_FILTER_KEEP_STRUCTURE).

    -

    Note that group objects are also ignored individually (without the entire level) when they do not bring structure.

    - - - - - -
    Enumerator
    HWLOC_TYPE_FILTER_KEEP_ALL 

    Keep all objects of this type.

    -

    Cannot be set for HWLOC_OBJ_GROUP (groups are designed only to add more structure to the topology).

    -
    HWLOC_TYPE_FILTER_KEEP_NONE 

    Ignore all objects of this type.

    -

    The bottom-level type HWLOC_OBJ_PU, the HWLOC_OBJ_NUMANODE type, and the top-level type HWLOC_OBJ_MACHINE may not be ignored.

    -
    HWLOC_TYPE_FILTER_KEEP_STRUCTURE 

    Only ignore objects if their entire level does not bring any structure.

    -

    Keep the entire level of objects if at least one of these objects adds structure to the topology. An object brings structure when it has multiple children and it is not the only child of its parent.

    -

    If all objects in the level are the only child of their parent, and if none of them has multiple children, the entire level is removed.

    -

    Cannot be set for I/O and Misc objects since the topology structure does not matter there.

    -
    HWLOC_TYPE_FILTER_KEEP_IMPORTANT 

    Only keep likely-important objects of the given type.

    -

    It is only useful for I/O object types. For HWLOC_OBJ_PCI_DEVICE and HWLOC_OBJ_OS_DEVICE, it means that only objects of major/common kinds are kept (storage, network, OpenFabrics, CUDA, OpenCL, RSMI, NVML, and displays). Also, only OS devices directly attached on PCI (e.g. no USB) are reported. For HWLOC_OBJ_BRIDGE, it means that bridges are kept only if they have children.

    -

    This flag equivalent to HWLOC_TYPE_FILTER_KEEP_ALL for Normal, Memory and Misc types since they are likely important.

    -
    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_topology_get_flags()

    - -
    -
    - - - - - - - - -
    unsigned long hwloc_topology_get_flags (hwloc_topology_t topology)
    -
    - -

    Get OR'ed flags of a topology.

    -

    Get the OR'ed set of hwloc_topology_flags_e of a topology.

    -

    If hwloc_topology_set_flags() was not called earlier, no flags are set (0 is returned).

    -
    Returns
    the flags previously set with hwloc_topology_set_flags().
    - -
    -
    - -

    ◆ hwloc_topology_get_support()

    - -
    -
    - - - - - - - - -
    const struct hwloc_topology_support* hwloc_topology_get_support (hwloc_topology_t restrict topology)
    -
    - -

    Retrieve the topology support.

    -

    Each flag indicates whether a feature is supported. If set to 0, the feature is not supported. If set to 1, the feature is supported, but the corresponding call may still fail in some corner cases.

    -

    These features are also listed by hwloc-info --support

    -

    The reported features are what the current topology supports on the current machine. If the topology was exported to XML from another machine and later imported here, support still describes what is supported for this imported topology after import. By default, binding will be reported as unsupported in this case (see HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM).

    -

    Topology flag HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT may be used to report the supported features of the original remote machine instead. If it was successfully imported, imported_support will be set in the struct hwloc_topology_misc_support array.

    - -
    -
    - -

    ◆ hwloc_topology_get_type_filter()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_get_type_filter (hwloc_topology_t topology,
    hwloc_obj_type_t type,
    enum hwloc_type_filter_e * filter 
    )
    -
    - -

    Get the current filtering for the given object type.

    - -
    -
    - -

    ◆ hwloc_topology_get_userdata()

    - -
    -
    - - - - - - - - -
    void* hwloc_topology_get_userdata (hwloc_topology_t topology)
    -
    - -

    Retrieve the topology-specific userdata pointer.

    -

    Retrieve the application-given private data pointer that was previously set with hwloc_topology_set_userdata().

    - -
    -
    - -

    ◆ hwloc_topology_is_thissystem()

    - -
    -
    - - - - - - - - -
    int hwloc_topology_is_thissystem (hwloc_topology_t restrict topology)
    -
    - -

    Does the topology context come from this system?

    -
    Returns
    1 if this topology context was built using the system running this program.
    -
    -0 instead (for instance if using another file-system root, a XML topology file, or a synthetic topology).
    - -
    -
    - -

    ◆ hwloc_topology_set_all_types_filter()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_set_all_types_filter (hwloc_topology_t topology,
    enum hwloc_type_filter_e filter 
    )
    -
    - -

    Set the filtering for all object types.

    -

    If some types do not support this filtering, they are silently ignored.

    - -
    -
    - -

    ◆ hwloc_topology_set_cache_types_filter()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_set_cache_types_filter (hwloc_topology_t topology,
    enum hwloc_type_filter_e filter 
    )
    -
    - -

    Set the filtering for all CPU cache object types.

    -

    Memory-side caches are not involved since they are not CPU caches.

    - -
    -
    - -

    ◆ hwloc_topology_set_flags()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_set_flags (hwloc_topology_t topology,
    unsigned long flags 
    )
    -
    - -

    Set OR'ed flags to non-yet-loaded topology.

    -

    Set a OR'ed set of hwloc_topology_flags_e onto a topology that was not yet loaded.

    -

    If this function is called multiple times, the last invocation will erase and replace the set of flags that was previously set.

    -

    By default, no flags are set (0).

    -

    The flags set in a topology may be retrieved with hwloc_topology_get_flags().

    - -
    -
    - -

    ◆ hwloc_topology_set_icache_types_filter()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_set_icache_types_filter (hwloc_topology_t topology,
    enum hwloc_type_filter_e filter 
    )
    -
    - -

    Set the filtering for all CPU instruction cache object types.

    -

    Memory-side caches are not involved since they are not CPU caches.

    - -
    -
    - -

    ◆ hwloc_topology_set_io_types_filter()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_set_io_types_filter (hwloc_topology_t topology,
    enum hwloc_type_filter_e filter 
    )
    -
    - -

    Set the filtering for all I/O object types.

    - -
    -
    - -

    ◆ hwloc_topology_set_type_filter()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_set_type_filter (hwloc_topology_t topology,
    hwloc_obj_type_t type,
    enum hwloc_type_filter_e filter 
    )
    -
    - -

    Set the filtering for the given object type.

    - -
    -
    - -

    ◆ hwloc_topology_set_userdata()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    void hwloc_topology_set_userdata (hwloc_topology_t topology,
    const void * userdata 
    )
    -
    - -

    Set the topology-specific userdata pointer.

    -

    Each topology may store one application-given private data pointer. It is initialized to NULL. hwloc will never modify it.

    -

    Use it as you wish, after hwloc_topology_init() and until hwloc_topolog_destroy().

    -

    This pointer is not exported to XML.

    - -
    -
    -
    - - - - - - - -
    -
    -Enumerations | -Functions
    -
    -
    Modifying a loaded Topology
    -
    -
    - - - - - - -

    -Enumerations

    enum  hwloc_restrict_flags_e {
    -  HWLOC_RESTRICT_FLAG_REMOVE_CPULESS -, HWLOC_RESTRICT_FLAG_BYNODESET = (1UL<<3) -, HWLOC_RESTRICT_FLAG_REMOVE_MEMLESS -, HWLOC_RESTRICT_FLAG_ADAPT_MISC -,
    -  HWLOC_RESTRICT_FLAG_ADAPT_IO -
    - }
     
    enum  hwloc_allow_flags_e { HWLOC_ALLOW_FLAG_ALL -, HWLOC_ALLOW_FLAG_LOCAL_RESTRICTIONS -, HWLOC_ALLOW_FLAG_CUSTOM - }
     
    - - - - - - - - - - - - - - - -

    -Functions

    int hwloc_topology_restrict (hwloc_topology_t restrict topology, hwloc_const_bitmap_t set, unsigned long flags)
     
    int hwloc_topology_allow (hwloc_topology_t restrict topology, hwloc_const_cpuset_t cpuset, hwloc_const_nodeset_t nodeset, unsigned long flags)
     
    hwloc_obj_t hwloc_topology_insert_misc_object (hwloc_topology_t topology, hwloc_obj_t parent, const char *name)
     
    hwloc_obj_t hwloc_topology_alloc_group_object (hwloc_topology_t topology)
     
    hwloc_obj_t hwloc_topology_insert_group_object (hwloc_topology_t topology, hwloc_obj_t group)
     
    int hwloc_obj_add_other_obj_sets (hwloc_obj_t dst, hwloc_obj_t src)
     
    int hwloc_topology_refresh (hwloc_topology_t topology)
     
    -

    Detailed Description

    -

    Enumeration Type Documentation

    - -

    ◆ hwloc_allow_flags_e

    - -
    -
    - - - - -
    enum hwloc_allow_flags_e
    -
    - -

    Flags to be given to hwloc_topology_allow().

    - - - - -
    Enumerator
    HWLOC_ALLOW_FLAG_ALL 

    Mark all objects as allowed in the topology.

    -

    cpuset and nođeset given to hwloc_topology_allow() must be NULL.

    -
    HWLOC_ALLOW_FLAG_LOCAL_RESTRICTIONS 

    Only allow objects that are available to the current process.

    -

    The topology must have HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM so that the set of available resources can actually be retrieved from the operating system.

    -

    cpuset and nođeset given to hwloc_topology_allow() must be NULL.

    -
    HWLOC_ALLOW_FLAG_CUSTOM 

    Allow a custom set of objects, given to hwloc_topology_allow() as cpuset and/or nodeset parameters.

    -
    - -
    -
    - -

    ◆ hwloc_restrict_flags_e

    - -
    -
    - - - - -
    enum hwloc_restrict_flags_e
    -
    - -

    Flags to be given to hwloc_topology_restrict().

    - - - - - - -
    Enumerator
    HWLOC_RESTRICT_FLAG_REMOVE_CPULESS 

    Remove all objects that became CPU-less. By default, only objects that contain no PU and no memory are removed. This flag may not be used with HWLOC_RESTRICT_FLAG_BYNODESET.

    -
    HWLOC_RESTRICT_FLAG_BYNODESET 

    Restrict by nodeset instead of CPU set. Only keep objects whose nodeset is included or partially included in the given set. This flag may not be used with HWLOC_RESTRICT_FLAG_REMOVE_CPULESS.

    -
    HWLOC_RESTRICT_FLAG_REMOVE_MEMLESS 

    Remove all objects that became Memory-less. By default, only objects that contain no PU and no memory are removed. This flag may only be used with HWLOC_RESTRICT_FLAG_BYNODESET.

    -
    HWLOC_RESTRICT_FLAG_ADAPT_MISC 

    Move Misc objects to ancestors if their parents are removed during restriction. If this flag is not set, Misc objects are removed when their parents are removed.

    -
    HWLOC_RESTRICT_FLAG_ADAPT_IO 

    Move I/O objects to ancestors if their parents are removed during restriction. If this flag is not set, I/O devices and bridges are removed when their parents are removed.

    -
    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_obj_add_other_obj_sets()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_obj_add_other_obj_sets (hwloc_obj_t dst,
    hwloc_obj_t src 
    )
    -
    - -

    Setup object cpusets/nodesets by OR'ing another object's sets.

    -

    For each defined cpuset or nodeset in src, allocate the corresponding set in dst and add src to it by OR'ing sets.

    -

    This function is convenient between hwloc_topology_alloc_group_object() and hwloc_topology_insert_group_object(). It builds the sets of the new Group that will be inserted as a new intermediate parent of several objects.

    - -
    -
    - -

    ◆ hwloc_topology_alloc_group_object()

    - -
    -
    - - - - - - - - -
    hwloc_obj_t hwloc_topology_alloc_group_object (hwloc_topology_t topology)
    -
    - -

    Allocate a Group object to insert later with hwloc_topology_insert_group_object().

    -

    This function returns a new Group object.

    -

    The caller should (at least) initialize its sets before inserting the object in the topology. See hwloc_topology_insert_group_object().

    - -
    -
    - -

    ◆ hwloc_topology_allow()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_allow (hwloc_topology_t restrict topology,
    hwloc_const_cpuset_t cpuset,
    hwloc_const_nodeset_t nodeset,
    unsigned long flags 
    )
    -
    - -

    Change the sets of allowed PUs and NUMA nodes in the topology.

    -

    This function only works if the HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED was set on the topology. It does not modify any object, it only changes the sets returned by hwloc_topology_get_allowed_cpuset() and hwloc_topology_get_allowed_nodeset().

    -

    It is notably useful when importing a topology from another process running in a different Linux Cgroup.

    -

    flags must be set to one flag among hwloc_allow_flags_e.

    -
    Note
    Removing objects from a topology should rather be performed with hwloc_topology_restrict().
    - -
    -
    - -

    ◆ hwloc_topology_insert_group_object()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    hwloc_obj_t hwloc_topology_insert_group_object (hwloc_topology_t topology,
    hwloc_obj_t group 
    )
    -
    - -

    Add more structure to the topology by adding an intermediate Group.

    -

    The caller should first allocate a new Group object with hwloc_topology_alloc_group_object(). Then it must setup at least one of its CPU or node sets to specify the final location of the Group in the topology. Then the object can be passed to this function for actual insertion in the topology.

    -

    Either the cpuset or nodeset field (or both, if compatible) must be set to a non-empty bitmap. The complete_cpuset or complete_nodeset may be set instead if inserting with respect to the complete topology (including disallowed, offline or unknown objects). If grouping several objects, hwloc_obj_add_other_obj_sets() is an easy way to build the Group sets iteratively. These sets cannot be larger than the current topology, or they would get restricted silently. The core will setup the other sets after actual insertion.

    -

    The subtype object attribute may be defined (to a dynamically allocated string) to display something else than "Group" as the type name for this object in lstopo. Custom name/value info pairs may be added with hwloc_obj_add_info() after insertion.

    -

    The group dont_merge attribute may be set to 1 to prevent the hwloc core from ever merging this object with another hierarchically-identical object. This is useful when the Group itself describes an important feature that cannot be exposed anywhere else in the hierarchy.

    -

    The group kind attribute may be set to a high value such as 0xffffffff to tell hwloc that this new Group should always be discarded in favor of any existing Group with the same locality.

    -
    Returns
    The inserted object if it was properly inserted.
    -
    -An existing object if the Group was merged or discarded because the topology already contained an object at the same location (the Group did not add any hierarchy information).
    -
    -NULL if the insertion failed because of conflicting sets in topology tree.
    -
    -NULL if Group objects are filtered-out of the topology (HWLOC_TYPE_FILTER_KEEP_NONE).
    -
    -NULL if the object was discarded because no set was initialized in the Group before insert, or all of them were empty.
    - -
    -
    - -

    ◆ hwloc_topology_insert_misc_object()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    hwloc_obj_t hwloc_topology_insert_misc_object (hwloc_topology_t topology,
    hwloc_obj_t parent,
    const char * name 
    )
    -
    - -

    Add a MISC object as a leaf of the topology.

    -

    A new MISC object will be created and inserted into the topology at the position given by parent. It is appended to the list of existing Misc children, without ever adding any intermediate hierarchy level. This is useful for annotating the topology without actually changing the hierarchy.

    -

    name is supposed to be unique across all Misc objects in the topology. It will be duplicated to setup the new object attributes.

    -

    The new leaf object will not have any cpuset.

    -
    Returns
    the newly-created object
    -
    -NULL on error.
    -
    -NULL if Misc objects are filtered-out of the topology (HWLOC_TYPE_FILTER_KEEP_NONE).
    -
    Note
    If name contains some non-printable characters, they will be dropped when exporting to XML, see hwloc_topology_export_xml() in hwloc/export.h.
    - -
    -
    - -

    ◆ hwloc_topology_refresh()

    - -
    -
    - - - - - - - - -
    int hwloc_topology_refresh (hwloc_topology_t topology)
    -
    - -

    Refresh internal structures after topology modification.

    -

    Modifying the topology (by restricting, adding objects, modifying structures such as distances or memory attributes, etc.) may cause some internal caches to become invalid. These caches are automatically refreshed when accessed but this refreshing is not thread-safe.

    -

    This function is not thread-safe either, but it is a good way to end a non-thread-safe phase of topology modification. Once this refresh is done, multiple threads may concurrently consult the topology, objects, distances, attributes, etc.

    -

    See also Thread Safety

    - -
    -
    - -

    ◆ hwloc_topology_restrict()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_restrict (hwloc_topology_t restrict topology,
    hwloc_const_bitmap_t set,
    unsigned long flags 
    )
    -
    - -

    Restrict the topology to the given CPU set or nodeset.

    -

    Topology topology is modified so as to remove all objects that are not included (or partially included) in the CPU set set. All objects CPU and node sets are restricted accordingly.

    -

    If HWLOC_RESTRICT_FLAG_BYNODESET is passed in flags, set is considered a nodeset instead of a CPU set.

    -

    flags is a OR'ed set of hwloc_restrict_flags_e.

    -
    Note
    This call may not be reverted by restricting back to a larger set. Once dropped during restriction, objects may not be brought back, except by loading another topology with hwloc_topology_load().
    -
    Returns
    0 on success.
    -
    --1 with errno set to EINVAL if the input set is invalid. The topology is not modified in this case.
    -
    --1 with errno set to ENOMEM on failure to allocate internal data. The topology is reinitialized in this case. It should be either destroyed with hwloc_topology_destroy() or configured and loaded again.
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    -
    Finding Objects inside a CPU set
    -
    -
    - - - - - - - - - - - - - - - - - - - - -

    -Functions

    static hwloc_obj_t hwloc_get_first_largest_obj_inside_cpuset (hwloc_topology_t topology, hwloc_const_cpuset_t set)
     
    int hwloc_get_largest_objs_inside_cpuset (hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_t *restrict objs, int max)
     
    static hwloc_obj_t hwloc_get_next_obj_inside_cpuset_by_depth (hwloc_topology_t topology, hwloc_const_cpuset_t set, int depth, hwloc_obj_t prev)
     
    static hwloc_obj_t hwloc_get_next_obj_inside_cpuset_by_type (hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_type_t type, hwloc_obj_t prev)
     
    static hwloc_obj_t hwloc_get_obj_inside_cpuset_by_depth (hwloc_topology_t topology, hwloc_const_cpuset_t set, int depth, unsigned idx)
     
    static hwloc_obj_t hwloc_get_obj_inside_cpuset_by_type (hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_type_t type, unsigned idx)
     
    static unsigned hwloc_get_nbobjs_inside_cpuset_by_depth (hwloc_topology_t topology, hwloc_const_cpuset_t set, int depth)
     
    static int hwloc_get_nbobjs_inside_cpuset_by_type (hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_type_t type)
     
    static int hwloc_get_obj_index_inside_cpuset (hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_t obj)
     
    -

    Detailed Description

    -

    Function Documentation

    - -

    ◆ hwloc_get_first_largest_obj_inside_cpuset()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_first_largest_obj_inside_cpuset (hwloc_topology_t topology,
    hwloc_const_cpuset_t set 
    )
    -     		-inlinestatic
    -
    - -

    Get the first largest object included in the given cpuset set.

    -
    Returns
    the first object that is included in set and whose parent is not.
    -

    This is convenient for iterating over all largest objects within a CPU set by doing a loop getting the first largest object and clearing its CPU set from the remaining CPU set.

    - -
    -
    - -

    ◆ hwloc_get_largest_objs_inside_cpuset()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_get_largest_objs_inside_cpuset (hwloc_topology_t topology,
    hwloc_const_cpuset_t set,
    hwloc_obj_t *restrict objs,
    int max 
    )
    -
    - -

    Get the set of largest objects covering exactly a given cpuset set.

    -
    Returns
    the number of objects returned in objs.
    - -
    -
    - -

    ◆ hwloc_get_nbobjs_inside_cpuset_by_depth()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static unsigned hwloc_get_nbobjs_inside_cpuset_by_depth (hwloc_topology_t topology,
    hwloc_const_cpuset_t set,
    int depth 
    )
    -     		-inlinestatic
    -
    - -

    Return the number of objects at depth depth included in CPU set set.

    -
    Note
    Objects with empty CPU sets are ignored (otherwise they would be considered included in any given set).
    -
    -This function cannot work if objects at the given depth do not have CPU sets (I/O or Misc objects).
    - -
    -
    - -

    ◆ hwloc_get_nbobjs_inside_cpuset_by_type()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_get_nbobjs_inside_cpuset_by_type (hwloc_topology_t topology,
    hwloc_const_cpuset_t set,
    hwloc_obj_type_t type 
    )
    -     		-inlinestatic
    -
    - -

    Return the number of objects of type type included in CPU set set.

    -

    If no object for that type exists inside CPU set set, 0 is returned. If there are several levels with objects of that type inside CPU set set, -1 is returned.

    -
    Note
    Objects with empty CPU sets are ignored (otherwise they would be considered included in any given set).
    -
    -This function cannot work if objects of the given type do not have CPU sets (I/O objects).
    - -
    -
    - -

    ◆ hwloc_get_next_obj_inside_cpuset_by_depth()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_next_obj_inside_cpuset_by_depth (hwloc_topology_t topology,
    hwloc_const_cpuset_t set,
    int depth,
    hwloc_obj_t prev 
    )
    -     		-inlinestatic
    -
    - -

    Return the next object at depth depth included in CPU set set.

    -

    If prev is NULL, return the first object at depth depth included in set. The next invokation should pass the previous return value in prev so as to obtain the next object in set.

    -
    Note
    Objects with empty CPU sets are ignored (otherwise they would be considered included in any given set).
    -
    -This function cannot work if objects at the given depth do not have CPU sets (I/O or Misc objects).
    - -
    -
    - -

    ◆ hwloc_get_next_obj_inside_cpuset_by_type()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_next_obj_inside_cpuset_by_type (hwloc_topology_t topology,
    hwloc_const_cpuset_t set,
    hwloc_obj_type_t type,
    hwloc_obj_t prev 
    )
    -     		-inlinestatic
    -
    - -

    Return the next object of type type included in CPU set set.

    -

    If there are multiple or no depth for given type, return NULL and let the caller fallback to hwloc_get_next_obj_inside_cpuset_by_depth().

    -
    Note
    Objects with empty CPU sets are ignored (otherwise they would be considered included in any given set).
    -
    -This function cannot work if objects of the given type do not have CPU sets (I/O or Misc objects).
    - -
    -
    - -

    ◆ hwloc_get_obj_index_inside_cpuset()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_get_obj_index_inside_cpuset (hwloc_topology_t topology,
    hwloc_const_cpuset_t set,
    hwloc_obj_t obj 
    )
    -     		-inlinestatic
    -
    - -

    Return the logical index among the objects included in CPU set set.

    -

    Consult all objects in the same level as obj and inside CPU set set in the logical order, and return the index of obj within them. If set covers the entire topology, this is the logical index of obj. Otherwise, this is similar to a logical index within the part of the topology defined by CPU set set.

    -
    Note
    Objects with empty CPU sets are ignored (otherwise they would be considered included in any given set).
    -
    -This function cannot work if obj does not have CPU sets (I/O objects).
    - -
    -
    - -

    ◆ hwloc_get_obj_inside_cpuset_by_depth()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_obj_inside_cpuset_by_depth (hwloc_topology_t topology,
    hwloc_const_cpuset_t set,
    int depth,
    unsigned idx 
    )
    -     		-inlinestatic
    -
    - -

    Return the (logically) idx -th object at depth depth included in CPU set set.

    -
    Note
    Objects with empty CPU sets are ignored (otherwise they would be considered included in any given set).
    -
    -This function cannot work if objects at the given depth do not have CPU sets (I/O or Misc objects).
    - -
    -
    - -

    ◆ hwloc_get_obj_inside_cpuset_by_type()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_obj_inside_cpuset_by_type (hwloc_topology_t topology,
    hwloc_const_cpuset_t set,
    hwloc_obj_type_t type,
    unsigned idx 
    )
    -     		-inlinestatic
    -
    - -

    Return the idx -th object of type type included in CPU set set.

    -

    If there are multiple or no depth for given type, return NULL and let the caller fallback to hwloc_get_obj_inside_cpuset_by_depth().

    -
    Note
    Objects with empty CPU sets are ignored (otherwise they would be considered included in any given set).
    -
    -This function cannot work if objects of the given type do not have CPU sets (I/O or Misc objects).
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    -
    Finding Objects covering at least CPU set
    -
    -
    - - - - - - - - - - -

    -Functions

    static hwloc_obj_t hwloc_get_child_covering_cpuset (hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_t parent)
     
    static hwloc_obj_t hwloc_get_obj_covering_cpuset (hwloc_topology_t topology, hwloc_const_cpuset_t set)
     
    static hwloc_obj_t hwloc_get_next_obj_covering_cpuset_by_depth (hwloc_topology_t topology, hwloc_const_cpuset_t set, int depth, hwloc_obj_t prev)
     
    static hwloc_obj_t hwloc_get_next_obj_covering_cpuset_by_type (hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_type_t type, hwloc_obj_t prev)
     
    -

    Detailed Description

    -

    Function Documentation

    - -

    ◆ hwloc_get_child_covering_cpuset()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_child_covering_cpuset (hwloc_topology_t topology,
    hwloc_const_cpuset_t set,
    hwloc_obj_t parent 
    )
    -     		-inlinestatic
    -
    - -

    Get the child covering at least CPU set set.

    -
    Returns
    NULL if no child matches or if set is empty.
    -
    Note
    This function cannot work if parent does not have a CPU set (I/O or Misc objects).
    - -
    -
    - -

    ◆ hwloc_get_next_obj_covering_cpuset_by_depth()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_next_obj_covering_cpuset_by_depth (hwloc_topology_t topology,
    hwloc_const_cpuset_t set,
    int depth,
    hwloc_obj_t prev 
    )
    -     		-inlinestatic
    -
    - -

    Iterate through same-depth objects covering at least CPU set set.

    -

    If object prev is NULL, return the first object at depth depth covering at least part of CPU set set. The next invokation should pass the previous return value in prev so as to obtain the next object covering at least another part of set.

    -
    Note
    This function cannot work if objects at the given depth do not have CPU sets (I/O or Misc objects).
    - -
    -
    - -

    ◆ hwloc_get_next_obj_covering_cpuset_by_type()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_next_obj_covering_cpuset_by_type (hwloc_topology_t topology,
    hwloc_const_cpuset_t set,
    hwloc_obj_type_t type,
    hwloc_obj_t prev 
    )
    -     		-inlinestatic
    -
    - -

    Iterate through same-type objects covering at least CPU set set.

    -

    If object prev is NULL, return the first object of type type covering at least part of CPU set set. The next invokation should pass the previous return value in prev so as to obtain the next object of type type covering at least another part of set.

    -

    If there are no or multiple depths for type type, NULL is returned. The caller may fallback to hwloc_get_next_obj_covering_cpuset_by_depth() for each depth.

    -
    Note
    This function cannot work if objects of the given type do not have CPU sets (I/O or Misc objects).
    - -
    -
    - -

    ◆ hwloc_get_obj_covering_cpuset()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_obj_covering_cpuset (hwloc_topology_t topology,
    hwloc_const_cpuset_t set 
    )
    -     		-inlinestatic
    -
    - -

    Get the lowest object covering at least CPU set set.

    -
    Returns
    NULL if no object matches or if set is empty.
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    -
    Looking at Ancestor and Child Objects
    -
    -
    - - - - - - - - - - - - -

    -Functions

    static hwloc_obj_t hwloc_get_ancestor_obj_by_depth (hwloc_topology_t topology, int depth, hwloc_obj_t obj)
     
    static hwloc_obj_t hwloc_get_ancestor_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, hwloc_obj_t obj)
     
    static hwloc_obj_t hwloc_get_common_ancestor_obj (hwloc_topology_t topology, hwloc_obj_t obj1, hwloc_obj_t obj2)
     
    static int hwloc_obj_is_in_subtree (hwloc_topology_t topology, hwloc_obj_t obj, hwloc_obj_t subtree_root)
     
    static hwloc_obj_t hwloc_get_next_child (hwloc_topology_t topology, hwloc_obj_t parent, hwloc_obj_t prev)
     
    -

    Detailed Description

    -

    Be sure to see the figure in Terms and Definitions that shows a complete topology tree, including depths, child/sibling/cousin relationships, and an example of an asymmetric topology where one package has fewer caches than its peers.

    -

    Function Documentation

    - -

    ◆ hwloc_get_ancestor_obj_by_depth()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_ancestor_obj_by_depth (hwloc_topology_t topology,
    int depth,
    hwloc_obj_t obj 
    )
    -     		-inlinestatic
    -
    - -

    Returns the ancestor object of obj at depth depth.

    -
    Note
    depth should not be the depth of PU or NUMA objects since they are ancestors of no objects (except Misc or I/O). This function rather expects an intermediate level depth, such as the depth of Packages, Cores, or Caches.
    - -
    -
    - -

    ◆ hwloc_get_ancestor_obj_by_type()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_ancestor_obj_by_type (hwloc_topology_t topology,
    hwloc_obj_type_t type,
    hwloc_obj_t obj 
    )
    -     		-inlinestatic
    -
    - -

    Returns the ancestor object of obj with type type.

    -
    Note
    type should not be HWLOC_OBJ_PU or HWLOC_OBJ_NUMANODE since these objects are ancestors of no objects (except Misc or I/O). This function rather expects an intermediate object type, such as HWLOC_OBJ_PACKAGE, HWLOC_OBJ_CORE, etc.
    - -
    -
    - -

    ◆ hwloc_get_common_ancestor_obj()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_common_ancestor_obj (hwloc_topology_t topology,
    hwloc_obj_t obj1,
    hwloc_obj_t obj2 
    )
    -     		-inlinestatic
    -
    - -

    Returns the common parent object to objects obj1 and obj2.

    - -
    -
    - -

    ◆ hwloc_get_next_child()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_next_child (hwloc_topology_t topology,
    hwloc_obj_t parent,
    hwloc_obj_t prev 
    )
    -     		-inlinestatic
    -
    - -

    Return the next child.

    -

    Return the next child among the normal children list, then among the memory children list, then among the I/O children list, then among the Misc children list.

    -

    If prev is NULL, return the first child.

    -

    Return NULL when there is no next child.

    - -
    -
    - -

    ◆ hwloc_obj_is_in_subtree()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_obj_is_in_subtree (hwloc_topology_t topology,
    hwloc_obj_t obj,
    hwloc_obj_t subtree_root 
    )
    -     		-inlinestatic
    -
    - -

    Returns true if obj is inside the subtree beginning with ancestor object subtree_root.

    -
    Note
    This function cannot work if obj and subtree_root objects do not have CPU sets (I/O or Misc objects).
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    -
    Kinds of object Type
    -
    -
    - - - - - - - - - - - - - - -

    -Functions

    int hwloc_obj_type_is_normal (hwloc_obj_type_t type)
     
    int hwloc_obj_type_is_io (hwloc_obj_type_t type)
     
    int hwloc_obj_type_is_memory (hwloc_obj_type_t type)
     
    int hwloc_obj_type_is_cache (hwloc_obj_type_t type)
     
    int hwloc_obj_type_is_dcache (hwloc_obj_type_t type)
     
    int hwloc_obj_type_is_icache (hwloc_obj_type_t type)
     
    -

    Detailed Description

    -

    Each object type is either Normal (i.e. hwloc_obj_type_is_normal() returns 1), or Memory (i.e. hwloc_obj_type_is_memory() returns 1) or I/O (i.e. hwloc_obj_type_is_io() returns 1) or Misc (i.e. equal to HWLOC_OBJ_MISC). It cannot be of more than one of these kinds.

    -

    Function Documentation

    - -

    ◆ hwloc_obj_type_is_cache()

    - -
    -
    - - - - - - - - -
    int hwloc_obj_type_is_cache (hwloc_obj_type_t type)
    -
    - -

    Check whether an object type is a CPU Cache (Data, Unified or Instruction).

    -

    Memory-side caches are not CPU caches.

    -
    Returns
    1 if an object of type type is a Cache, 0 otherwise.
    - -
    -
    - -

    ◆ hwloc_obj_type_is_dcache()

    - -
    -
    - - - - - - - - -
    int hwloc_obj_type_is_dcache (hwloc_obj_type_t type)
    -
    - -

    Check whether an object type is a CPU Data or Unified Cache.

    -

    Memory-side caches are not CPU caches.

    -
    Returns
    1 if an object of type type is a CPU Data or Unified Cache, 0 otherwise.
    - -
    -
    - -

    ◆ hwloc_obj_type_is_icache()

    - -
    -
    - - - - - - - - -
    int hwloc_obj_type_is_icache (hwloc_obj_type_t type)
    -
    - -

    Check whether an object type is a CPU Instruction Cache,.

    -

    Memory-side caches are not CPU caches.

    -
    Returns
    1 if an object of type type is a CPU Instruction Cache, 0 otherwise.
    - -
    -
    - -

    ◆ hwloc_obj_type_is_io()

    - -
    -
    - - - - - - - - -
    int hwloc_obj_type_is_io (hwloc_obj_type_t type)
    -
    - -

    Check whether an object type is I/O.

    -

    I/O objects are objects attached to their parents in the I/O children list. This current includes Bridges, PCI and OS devices.

    -
    Returns
    1 if an object of type type is a I/O object, 0 otherwise.
    - -
    -
    - -

    ◆ hwloc_obj_type_is_memory()

    - -
    -
    - - - - - - - - -
    int hwloc_obj_type_is_memory (hwloc_obj_type_t type)
    -
    - -

    Check whether an object type is Memory.

    -

    Memory objects are objects attached to their parents in the Memory children list. This current includes NUMA nodes and Memory-side caches.

    -
    Returns
    1 if an object of type type is a Memory object, 0 otherwise.
    - -
    -
    - -

    ◆ hwloc_obj_type_is_normal()

    - -
    -
    - - - - - - - - -
    int hwloc_obj_type_is_normal (hwloc_obj_type_t type)
    -
    - -

    Check whether an object type is Normal.

    -

    Normal objects are objects of the main CPU hierarchy (Machine, Package, Core, PU, CPU caches, etc.), but they are not NUMA nodes, I/O devices or Misc objects.

    -

    They are attached to parent as Normal children, not as Memory, I/O or Misc children.

    -
    Returns
    1 if an object of type type is a Normal object, 0 otherwise.
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    -
    Looking at Cache Objects
    -
    -
    - - - - - - - - -

    -Functions

    static int hwloc_get_cache_type_depth (hwloc_topology_t topology, unsigned cachelevel, hwloc_obj_cache_type_t cachetype)
     
    static hwloc_obj_t hwloc_get_cache_covering_cpuset (hwloc_topology_t topology, hwloc_const_cpuset_t set)
     
    static hwloc_obj_t hwloc_get_shared_cache_covering_obj (hwloc_topology_t topology, hwloc_obj_t obj)
     
    -

    Detailed Description

    -

    Function Documentation

    - -

    ◆ hwloc_get_cache_covering_cpuset()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_cache_covering_cpuset (hwloc_topology_t topology,
    hwloc_const_cpuset_t set 
    )
    -     		-inlinestatic
    -
    - -

    Get the first data (or unified) cache covering a cpuset set.

    -
    Returns
    NULL if no cache matches.
    - -
    -
    - -

    ◆ hwloc_get_cache_type_depth()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_get_cache_type_depth (hwloc_topology_t topology,
    unsigned cachelevel,
    hwloc_obj_cache_type_t cachetype 
    )
    -     		-inlinestatic
    -
    - -

    Find the depth of cache objects matching cache level and type.

    -

    Return the depth of the topology level that contains cache objects whose attributes match cachelevel and cachetype.

    -

    This function is identical to calling hwloc_get_type_depth() with the corresponding type such as HWLOC_OBJ_L1ICACHE, except that it may also return a Unified cache when looking for an instruction cache.

    -

    If no cache level matches, HWLOC_TYPE_DEPTH_UNKNOWN is returned.

    -

    If cachetype is HWLOC_OBJ_CACHE_UNIFIED, the depth of the unique matching unified cache level is returned.

    -

    If cachetype is HWLOC_OBJ_CACHE_DATA or HWLOC_OBJ_CACHE_INSTRUCTION, either a matching cache, or a unified cache is returned.

    -

    If cachetype is -1, it is ignored and multiple levels may match. The function returns either the depth of a uniquely matching level or HWLOC_TYPE_DEPTH_MULTIPLE.

    - -
    -
    - -

    ◆ hwloc_get_shared_cache_covering_obj()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_shared_cache_covering_obj (hwloc_topology_t topology,
    hwloc_obj_t obj 
    )
    -     		-inlinestatic
    -
    - -

    Get the first data (or unified) cache shared between an object and somebody else.

    -
    Returns
    NULL if no cache matches or if an invalid object is given.
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    -
    Finding objects, miscellaneous helpers
    -
    -
    - - - - - - - - - - - - - - - - -

    -Functions

    int hwloc_bitmap_singlify_per_core (hwloc_topology_t topology, hwloc_bitmap_t cpuset, unsigned which)
     
    static hwloc_obj_t hwloc_get_pu_obj_by_os_index (hwloc_topology_t topology, unsigned os_index)
     
    static hwloc_obj_t hwloc_get_numanode_obj_by_os_index (hwloc_topology_t topology, unsigned os_index)
     
    unsigned hwloc_get_closest_objs (hwloc_topology_t topology, hwloc_obj_t src, hwloc_obj_t *restrict objs, unsigned max)
     
    static hwloc_obj_t hwloc_get_obj_below_by_type (hwloc_topology_t topology, hwloc_obj_type_t type1, unsigned idx1, hwloc_obj_type_t type2, unsigned idx2)
     
    static hwloc_obj_t hwloc_get_obj_below_array_by_type (hwloc_topology_t topology, int nr, hwloc_obj_type_t *typev, unsigned *idxv)
     
    hwloc_obj_t hwloc_get_obj_with_same_locality (hwloc_topology_t topology, hwloc_obj_t src, hwloc_obj_type_t type, const char *subtype, const char *nameprefix, unsigned long flags)
     
    -

    Detailed Description

    -

    Be sure to see the figure in Terms and Definitions that shows a complete topology tree, including depths, child/sibling/cousin relationships, and an example of an asymmetric topology where one package has fewer caches than its peers.

    -

    Function Documentation

    - -

    ◆ hwloc_bitmap_singlify_per_core()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_singlify_per_core (hwloc_topology_t topology,
    hwloc_bitmap_t cpuset,
    unsigned which 
    )
    -
    - -

    Remove simultaneous multithreading PUs from a CPU set.

    -

    For each core in topology, if cpuset contains some PUs of that core, modify cpuset to only keep a single PU for that core.

    -

    which specifies which PU will be kept. PU are considered in physical index order. If 0, for each core, the function keeps the first PU that was originally set in cpuset.

    -

    If which is larger than the number of PUs in a core there were originally set in cpuset, no PU is kept for that core.

    -
    Note
    PUs that are not below a Core object are ignored (for instance if the topology does not contain any Core object). None of them is removed from cpuset.
    - -
    -
    - -

    ◆ hwloc_get_closest_objs()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    unsigned hwloc_get_closest_objs (hwloc_topology_t topology,
    hwloc_obj_t src,
    hwloc_obj_t *restrict objs,
    unsigned max 
    )
    -
    - -

    Do a depth-first traversal of the topology to find and sort.

    -

    all objects that are at the same depth than src. Report in objs up to max physically closest ones to src.

    -
    Returns
    the number of objects returned in objs.
    -
    -0 if src is an I/O object.
    -
    Note
    This function requires the src object to have a CPU set.
    - -
    -
    - -

    ◆ hwloc_get_numanode_obj_by_os_index()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_numanode_obj_by_os_index (hwloc_topology_t topology,
    unsigned os_index 
    )
    -     		-inlinestatic
    -
    - -

    Returns the object of type HWLOC_OBJ_NUMANODE with os_index.

    -

    This function is useful for converting a nodeset into the NUMA node objects it contains. When retrieving the current binding (e.g. with hwloc_get_membind() with HWLOC_MEMBIND_BYNODESET), one may iterate over the bits of the resulting nodeset with hwloc_bitmap_foreach_begin(), and find the corresponding NUMA nodes with this function.

    - -
    -
    - -

    ◆ hwloc_get_obj_below_array_by_type()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_obj_below_array_by_type (hwloc_topology_t topology,
    int nr,
    hwloc_obj_type_t * typev,
    unsigned * idxv 
    )
    -     		-inlinestatic
    -
    - -

    Find an object below a chain of objects specified by types and indexes.

    -

    This is a generalized version of hwloc_get_obj_below_by_type().

    -

    Arrays typev and idxv must contain nr types and indexes.

    -

    Start from the top system object and walk the arrays typev and idxv. For each type and logical index couple in the arrays, look under the previously found object to find the index-th object of the given type. Indexes are specified within the parent, not withing the entire system.

    -

    For instance, if nr is 3, typev contains NODE, PACKAGE and CORE, and idxv contains 0, 1 and 2, return the third core object below the second package below the first NUMA node.

    -
    Note
    This function requires all these objects and the root object to have a CPU set.
    - -
    -
    - -

    ◆ hwloc_get_obj_below_by_type()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_obj_below_by_type (hwloc_topology_t topology,
    hwloc_obj_type_t type1,
    unsigned idx1,
    hwloc_obj_type_t type2,
    unsigned idx2 
    )
    -     		-inlinestatic
    -
    - -

    Find an object below another object, both specified by types and indexes.

    -

    Start from the top system object and find object of type type1 and logical index idx1. Then look below this object and find another object of type type2 and logical index idx2. Indexes are specified within the parent, not withing the entire system.

    -

    For instance, if type1 is PACKAGE, idx1 is 2, type2 is CORE and idx2 is 3, return the fourth core object below the third package.

    -
    Note
    This function requires these objects to have a CPU set.
    - -
    -
    - -

    ◆ hwloc_get_obj_with_same_locality()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    hwloc_obj_t hwloc_get_obj_with_same_locality (hwloc_topology_t topology,
    hwloc_obj_t src,
    hwloc_obj_type_t type,
    const char * subtype,
    const char * nameprefix,
    unsigned long flags 
    )
    -
    - -

    Return an object of a different type with same locality.

    -

    If the source object src is a normal or memory type, this function returns an object of type type with same CPU and node sets, either below or above in the hierarchy.

    -

    If the source object src is a PCI or an OS device within a PCI device, the function may either return that PCI device, or another OS device in the same PCI parent. This may for instance be useful for converting between OS devices such as "nvml0" or "rsmi1" used in distance structures into the the PCI device, or the CUDA or OpenCL OS device that correspond to the same physical card.

    -

    If not NULL, parameter subtype only select objects whose subtype attribute exists and is subtype (case-insensitively), for instance "OpenCL" or "CUDA".

    -

    If not NULL, parameter nameprefix only selects objects whose name attribute exists and starts with nameprefix (case-insensitively), for instance "rsmi" for matching "rsmi0".

    -

    If multiple objects match, the first one is returned.

    -

    This function will not walk the hierarchy across bridges since the PCI locality may become different. This function cannot also convert between normal/memory objects and I/O or Misc objects.

    -

    flags must be 0 for now.

    -
    Returns
    An object with identical locality, matching subtype and nameprefix if any.
    -
    -NULL if no matching object could be found, or if the source object and target type are incompatible, for instance if converting between CPU and I/O objects.
    - -
    -
    - -

    ◆ hwloc_get_pu_obj_by_os_index()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_pu_obj_by_os_index (hwloc_topology_t topology,
    unsigned os_index 
    )
    -     		-inlinestatic
    -
    - -

    Returns the object of type HWLOC_OBJ_PU with os_index.

    -

    This function is useful for converting a CPU set into the PU objects it contains. When retrieving the current binding (e.g. with hwloc_get_cpubind()), one may iterate over the bits of the resulting CPU set with hwloc_bitmap_foreach_begin(), and find the corresponding PUs with this function.

    - -
    -
    -
    - - - - - - - -
    -
    -Enumerations | -Functions
    -
    -
    Distributing items over a topology
    -
    -
    - - - - -

    -Enumerations

    enum  hwloc_distrib_flags_e { HWLOC_DISTRIB_FLAG_REVERSE - }
     
    - - - -

    -Functions

    static int hwloc_distrib (hwloc_topology_t topology, hwloc_obj_t *roots, unsigned n_roots, hwloc_cpuset_t *set, unsigned n, int until, unsigned long flags)
     
    -

    Detailed Description

    -

    Enumeration Type Documentation

    - -

    ◆ hwloc_distrib_flags_e

    - -
    -
    - - - - -
    enum hwloc_distrib_flags_e
    -
    - -

    Flags to be given to hwloc_distrib().

    - - -
    Enumerator
    HWLOC_DISTRIB_FLAG_REVERSE 

    Distrib in reverse order, starting from the last objects.

    -
    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_distrib()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_distrib (hwloc_topology_t topology,
    hwloc_obj_t * roots,
    unsigned n_roots,
    hwloc_cpuset_t * set,
    unsigned n,
    int until,
    unsigned long flags 
    )
    -     		-inlinestatic
    -
    - -

    Distribute n items over the topology under roots.

    -

    Array set will be filled with n cpusets recursively distributed linearly over the topology under objects roots, down to depth until (which can be INT_MAX to distribute down to the finest level).

    -

    n_roots is usually 1 and roots only contains the topology root object so as to distribute over the entire topology.

    -

    This is typically useful when an application wants to distribute n threads over a machine, giving each of them as much private cache as possible and keeping them locally in number order.

    -

    The caller may typically want to also call hwloc_bitmap_singlify() before binding a thread so that it does not move at all.

    -

    flags should be 0 or a OR'ed set of hwloc_distrib_flags_e.

    -
    Note
    This function requires the roots objects to have a CPU set.
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    -
    CPU and node sets of entire topologies
    -
    -
    - - - - - - - - - - - - - - -

    -Functions

    hwloc_const_cpuset_t hwloc_topology_get_complete_cpuset (hwloc_topology_t topology)
     
    hwloc_const_cpuset_t hwloc_topology_get_topology_cpuset (hwloc_topology_t topology)
     
    hwloc_const_cpuset_t hwloc_topology_get_allowed_cpuset (hwloc_topology_t topology)
     
    hwloc_const_nodeset_t hwloc_topology_get_complete_nodeset (hwloc_topology_t topology)
     
    hwloc_const_nodeset_t hwloc_topology_get_topology_nodeset (hwloc_topology_t topology)
     
    hwloc_const_nodeset_t hwloc_topology_get_allowed_nodeset (hwloc_topology_t topology)
     
    -

    Detailed Description

    -

    Function Documentation

    - -

    ◆ hwloc_topology_get_allowed_cpuset()

    - -
    -
    - - - - - - - - -
    hwloc_const_cpuset_t hwloc_topology_get_allowed_cpuset (hwloc_topology_t topology)
    -
    - -

    Get allowed CPU set.

    -
    Returns
    the CPU set of allowed processors of the system.
    -
    Note
    If the topology flag HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED was not set, this is identical to hwloc_topology_get_topology_cpuset(), which means all PUs are allowed.
    -
    -If HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED was set, applying hwloc_bitmap_intersects() on the result of this function and on an object cpuset checks whether there are allowed PUs inside that object. Applying hwloc_bitmap_and() returns the list of these allowed PUs.
    -
    -The returned cpuset is not newly allocated and should thus not be changed or freed, hwloc_bitmap_dup() must be used to obtain a local copy.
    - -
    -
    - -

    ◆ hwloc_topology_get_allowed_nodeset()

    - -
    -
    - - - - - - - - -
    hwloc_const_nodeset_t hwloc_topology_get_allowed_nodeset (hwloc_topology_t topology)
    -
    - -

    Get allowed node set.

    -
    Returns
    the node set of allowed memory of the system.
    -
    Note
    If the topology flag HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED was not set, this is identical to hwloc_topology_get_topology_nodeset(), which means all NUMA nodes are allowed.
    -
    -If HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED was set, applying hwloc_bitmap_intersects() on the result of this function and on an object nodeset checks whether there are allowed NUMA nodes inside that object. Applying hwloc_bitmap_and() returns the list of these allowed NUMA nodes.
    -
    -The returned nodeset is not newly allocated and should thus not be changed or freed, hwloc_bitmap_dup() must be used to obtain a local copy.
    - -
    -
    - -

    ◆ hwloc_topology_get_complete_cpuset()

    - -
    -
    - - - - - - - - -
    hwloc_const_cpuset_t hwloc_topology_get_complete_cpuset (hwloc_topology_t topology)
    -
    - -

    Get complete CPU set.

    -
    Returns
    the complete CPU set of processors of the system.
    -
    Note
    The returned cpuset is not newly allocated and should thus not be changed or freed; hwloc_bitmap_dup() must be used to obtain a local copy.
    -
    -This is equivalent to retrieving the root object complete CPU-set.
    - -
    -
    - -

    ◆ hwloc_topology_get_complete_nodeset()

    - -
    -
    - - - - - - - - -
    hwloc_const_nodeset_t hwloc_topology_get_complete_nodeset (hwloc_topology_t topology)
    -
    - -

    Get complete node set.

    -
    Returns
    the complete node set of memory of the system.
    -
    Note
    The returned nodeset is not newly allocated and should thus not be changed or freed; hwloc_bitmap_dup() must be used to obtain a local copy.
    -
    -This is equivalent to retrieving the root object complete nodeset.
    - -
    -
    - -

    ◆ hwloc_topology_get_topology_cpuset()

    - -
    -
    - - - - - - - - -
    hwloc_const_cpuset_t hwloc_topology_get_topology_cpuset (hwloc_topology_t topology)
    -
    - -

    Get topology CPU set.

    -
    Returns
    the CPU set of processors of the system for which hwloc provides topology information. This is equivalent to the cpuset of the system object.
    -
    Note
    The returned cpuset is not newly allocated and should thus not be changed or freed; hwloc_bitmap_dup() must be used to obtain a local copy.
    -
    -This is equivalent to retrieving the root object CPU-set.
    - -
    -
    - -

    ◆ hwloc_topology_get_topology_nodeset()

    - -
    -
    - - - - - - - - -
    hwloc_const_nodeset_t hwloc_topology_get_topology_nodeset (hwloc_topology_t topology)
    -
    - -

    Get topology node set.

    -
    Returns
    the node set of memory of the system for which hwloc provides topology information. This is equivalent to the nodeset of the system object.
    -
    Note
    The returned nodeset is not newly allocated and should thus not be changed or freed; hwloc_bitmap_dup() must be used to obtain a local copy.
    -
    -This is equivalent to retrieving the root object nodeset.
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    -
    Converting between CPU sets and node sets
    -
    -
    - - - - - - -

    -Functions

    static int hwloc_cpuset_to_nodeset (hwloc_topology_t topology, hwloc_const_cpuset_t _cpuset, hwloc_nodeset_t nodeset)
     
    static int hwloc_cpuset_from_nodeset (hwloc_topology_t topology, hwloc_cpuset_t _cpuset, hwloc_const_nodeset_t nodeset)
     
    -

    Detailed Description

    -

    Function Documentation

    - -

    ◆ hwloc_cpuset_from_nodeset()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_cpuset_from_nodeset (hwloc_topology_t topology,
    hwloc_cpuset_t _cpuset,
    hwloc_const_nodeset_t nodeset 
    )
    -     		-inlinestatic
    -
    - -

    Convert a NUMA node set into a CPU set.

    -

    For each NUMA node included in the input nodeset, set the corresponding local PUs in the output _cpuset.

    -

    If some CPUs have no local NUMA nodes, this function never sets their indexes in the output CPU set, even if a full node set is given in input.

    -

    Hence the entire topology node set is converted into the set of all CPUs that have some local NUMA nodes.

    - -
    -
    - -

    ◆ hwloc_cpuset_to_nodeset()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_cpuset_to_nodeset (hwloc_topology_t topology,
    hwloc_const_cpuset_t _cpuset,
    hwloc_nodeset_t nodeset 
    )
    -     		-inlinestatic
    -
    - -

    Convert a CPU set into a NUMA node set.

    -

    For each PU included in the input _cpuset, set the corresponding local NUMA node(s) in the output nodeset.

    -

    If some NUMA nodes have no CPUs at all, this function never sets their indexes in the output node set, even if a full CPU set is given in input.

    -

    Hence the entire topology CPU set is converted into the set of all nodes that have some local CPUs.

    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    -
    Finding I/O objects
    -
    -
    - - - - - - - - - - - - - - - - -

    -Functions

    static hwloc_obj_t hwloc_get_non_io_ancestor_obj (hwloc_topology_t topology, hwloc_obj_t ioobj)
     
    static hwloc_obj_t hwloc_get_next_pcidev (hwloc_topology_t topology, hwloc_obj_t prev)
     
    static hwloc_obj_t hwloc_get_pcidev_by_busid (hwloc_topology_t topology, unsigned domain, unsigned bus, unsigned dev, unsigned func)
     
    static hwloc_obj_t hwloc_get_pcidev_by_busidstring (hwloc_topology_t topology, const char *busid)
     
    static hwloc_obj_t hwloc_get_next_osdev (hwloc_topology_t topology, hwloc_obj_t prev)
     
    static hwloc_obj_t hwloc_get_next_bridge (hwloc_topology_t topology, hwloc_obj_t prev)
     
    static int hwloc_bridge_covers_pcibus (hwloc_obj_t bridge, unsigned domain, unsigned bus)
     
    -

    Detailed Description

    -

    Function Documentation

    - -

    ◆ hwloc_bridge_covers_pcibus()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_bridge_covers_pcibus (hwloc_obj_t bridge,
    unsigned domain,
    unsigned bus 
    )
    -     		-inlinestatic
    -
    - -
    -
    - -

    ◆ hwloc_get_next_bridge()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_next_bridge (hwloc_topology_t topology,
    hwloc_obj_t prev 
    )
    -     		-inlinestatic
    -
    - -

    Get the next bridge in the system.

    -
    Returns
    the first bridge if prev is NULL.
    - -
    -
    - -

    ◆ hwloc_get_next_osdev()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_next_osdev (hwloc_topology_t topology,
    hwloc_obj_t prev 
    )
    -     		-inlinestatic
    -
    - -

    Get the next OS device in the system.

    -
    Returns
    the first OS device if prev is NULL.
    - -
    -
    - -

    ◆ hwloc_get_next_pcidev()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_next_pcidev (hwloc_topology_t topology,
    hwloc_obj_t prev 
    )
    -     		-inlinestatic
    -
    - -

    Get the next PCI device in the system.

    -
    Returns
    the first PCI device if prev is NULL.
    - -
    -
    - -

    ◆ hwloc_get_non_io_ancestor_obj()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_non_io_ancestor_obj (hwloc_topology_t topology,
    hwloc_obj_t ioobj 
    )
    -     		-inlinestatic
    -
    - -

    Get the first non-I/O ancestor object.

    -

    Given the I/O object ioobj, find the smallest non-I/O ancestor object. This object (normal or memory) may then be used for binding because it has non-NULL CPU and node sets and because its locality is the same as ioobj.

    -
    Note
    The resulting object is usually a normal object but it could also be a memory object (e.g. NUMA node) in future platforms if I/O objects ever get attached to memory instead of CPUs.
    - -
    -
    - -

    ◆ hwloc_get_pcidev_by_busid()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_pcidev_by_busid (hwloc_topology_t topology,
    unsigned domain,
    unsigned bus,
    unsigned dev,
    unsigned func 
    )
    -     		-inlinestatic
    -
    - -

    Find the PCI device object matching the PCI bus id given domain, bus device and function PCI bus id.

    - -
    -
    - -

    ◆ hwloc_get_pcidev_by_busidstring()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_pcidev_by_busidstring (hwloc_topology_t topology,
    const char * busid 
    )
    -     		-inlinestatic
    -
    - -

    Find the PCI device object matching the PCI bus id given as a string xxxx:yy:zz.t or yy:zz.t.

    - -
    -
    -
    - - - - - - - -
    -
    -Macros | -Typedefs | -Functions
    -
    -
    The bitmap API
    -
    -
    - - - - - - -

    -Macros

    #define hwloc_bitmap_foreach_begin(id, bitmap)
     
    #define hwloc_bitmap_foreach_end()
     
    - - - - - -

    -Typedefs

    typedef struct hwloc_bitmap_s * hwloc_bitmap_t
     
    typedef const struct hwloc_bitmap_s * hwloc_const_bitmap_t
     
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

    -Functions

    hwloc_bitmap_t hwloc_bitmap_alloc (void)
     
    hwloc_bitmap_t hwloc_bitmap_alloc_full (void)
     
    void hwloc_bitmap_free (hwloc_bitmap_t bitmap)
     
    hwloc_bitmap_t hwloc_bitmap_dup (hwloc_const_bitmap_t bitmap)
     
    int hwloc_bitmap_copy (hwloc_bitmap_t dst, hwloc_const_bitmap_t src)
     
    int hwloc_bitmap_snprintf (char *restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap)
     
    int hwloc_bitmap_asprintf (char **strp, hwloc_const_bitmap_t bitmap)
     
    int hwloc_bitmap_sscanf (hwloc_bitmap_t bitmap, const char *restrict string)
     
    int hwloc_bitmap_list_snprintf (char *restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap)
     
    int hwloc_bitmap_list_asprintf (char **strp, hwloc_const_bitmap_t bitmap)
     
    int hwloc_bitmap_list_sscanf (hwloc_bitmap_t bitmap, const char *restrict string)
     
    int hwloc_bitmap_taskset_snprintf (char *restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap)
     
    int hwloc_bitmap_taskset_asprintf (char **strp, hwloc_const_bitmap_t bitmap)
     
    int hwloc_bitmap_taskset_sscanf (hwloc_bitmap_t bitmap, const char *restrict string)
     
    void hwloc_bitmap_zero (hwloc_bitmap_t bitmap)
     
    void hwloc_bitmap_fill (hwloc_bitmap_t bitmap)
     
    int hwloc_bitmap_only (hwloc_bitmap_t bitmap, unsigned id)
     
    int hwloc_bitmap_allbut (hwloc_bitmap_t bitmap, unsigned id)
     
    int hwloc_bitmap_from_ulong (hwloc_bitmap_t bitmap, unsigned long mask)
     
    int hwloc_bitmap_from_ith_ulong (hwloc_bitmap_t bitmap, unsigned i, unsigned long mask)
     
    int hwloc_bitmap_from_ulongs (hwloc_bitmap_t bitmap, unsigned nr, const unsigned long *masks)
     
    int hwloc_bitmap_set (hwloc_bitmap_t bitmap, unsigned id)
     
    int hwloc_bitmap_set_range (hwloc_bitmap_t bitmap, unsigned begin, int end)
     
    int hwloc_bitmap_set_ith_ulong (hwloc_bitmap_t bitmap, unsigned i, unsigned long mask)
     
    int hwloc_bitmap_clr (hwloc_bitmap_t bitmap, unsigned id)
     
    int hwloc_bitmap_clr_range (hwloc_bitmap_t bitmap, unsigned begin, int end)
     
    int hwloc_bitmap_singlify (hwloc_bitmap_t bitmap)
     
    unsigned long hwloc_bitmap_to_ulong (hwloc_const_bitmap_t bitmap)
     
    unsigned long hwloc_bitmap_to_ith_ulong (hwloc_const_bitmap_t bitmap, unsigned i)
     
    int hwloc_bitmap_to_ulongs (hwloc_const_bitmap_t bitmap, unsigned nr, unsigned long *masks)
     
    int hwloc_bitmap_nr_ulongs (hwloc_const_bitmap_t bitmap)
     
    int hwloc_bitmap_isset (hwloc_const_bitmap_t bitmap, unsigned id)
     
    int hwloc_bitmap_iszero (hwloc_const_bitmap_t bitmap)
     
    int hwloc_bitmap_isfull (hwloc_const_bitmap_t bitmap)
     
    int hwloc_bitmap_first (hwloc_const_bitmap_t bitmap)
     
    int hwloc_bitmap_next (hwloc_const_bitmap_t bitmap, int prev)
     
    int hwloc_bitmap_last (hwloc_const_bitmap_t bitmap)
     
    int hwloc_bitmap_weight (hwloc_const_bitmap_t bitmap)
     
    int hwloc_bitmap_first_unset (hwloc_const_bitmap_t bitmap)
     
    int hwloc_bitmap_next_unset (hwloc_const_bitmap_t bitmap, int prev)
     
    int hwloc_bitmap_last_unset (hwloc_const_bitmap_t bitmap)
     
    int hwloc_bitmap_or (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
     
    int hwloc_bitmap_and (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
     
    int hwloc_bitmap_andnot (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
     
    int hwloc_bitmap_xor (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
     
    int hwloc_bitmap_not (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap)
     
    int hwloc_bitmap_intersects (hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
     
    int hwloc_bitmap_isincluded (hwloc_const_bitmap_t sub_bitmap, hwloc_const_bitmap_t super_bitmap)
     
    int hwloc_bitmap_isequal (hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
     
    int hwloc_bitmap_compare_first (hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
     
    int hwloc_bitmap_compare (hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
     
    -

    Detailed Description

    -

    The hwloc_bitmap_t type represents a set of integers (positive or null). A bitmap may be of infinite size (all bits are set after some point). A bitmap may even be full if all bits are set.

    -

    Bitmaps are used by hwloc for sets of OS processors (which may actually be hardware threads) as by hwloc_cpuset_t (a typedef for hwloc_bitmap_t), or sets of NUMA memory nodes as hwloc_nodeset_t (also a typedef for hwloc_bitmap_t). Those are used for cpuset and nodeset fields in the hwloc_obj structure, see Object Sets (hwloc_cpuset_t and hwloc_nodeset_t).

    -

    Both CPU and node sets are always indexed by OS physical number. However users should usually not build CPU and node sets manually (e.g. with hwloc_bitmap_set()). One should rather use existing object sets and combine them with hwloc_bitmap_or(), etc. For instance, binding the current thread on a pair of cores may be performed with:

    hwloc_obj_t core1 = ... , core2 = ... ;
    -
    hwloc_bitmap_t set = hwloc_bitmap_alloc();
    -
    hwloc_bitmap_or(set, core1->cpuset, core2->cpuset);
    -
    hwloc_set_cpubind(topology, set, HWLOC_CPUBIND_THREAD);
    -
    hwloc_bitmap_free(set);
    -
    hwloc_set_cpubind
    int hwloc_set_cpubind(hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags)
    Bind current process or thread on CPUs given in physical bitmap set.
    -
    HWLOC_CPUBIND_THREAD
    @ HWLOC_CPUBIND_THREAD
    Bind current thread of current process.
    Definition: hwloc.h:1162
    -
    hwloc_bitmap_or
    int hwloc_bitmap_or(hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
    Or bitmaps bitmap1 and bitmap2 and store the result in bitmap res.
    -
    hwloc_bitmap_free
    void hwloc_bitmap_free(hwloc_bitmap_t bitmap)
    Free bitmap bitmap.
    -
    hwloc_bitmap_t
    struct hwloc_bitmap_s * hwloc_bitmap_t
    Set of bits represented as an opaque pointer to an internal bitmap.
    Definition: bitmap.h:68
    -
    hwloc_bitmap_alloc
    hwloc_bitmap_t hwloc_bitmap_alloc(void)
    Allocate a new empty bitmap.
    -
    hwloc_obj
    Structure of a topology object.
    Definition: hwloc.h:396
    -
    hwloc_obj::cpuset
    hwloc_cpuset_t cpuset
    CPUs covered by this object.
    Definition: hwloc.h:512
    -
    Note
    Most functions below return an int that may be negative in case of error. The usual error case would be an internal failure to realloc/extend the storage of the bitmap (errno would be set to ENOMEM).
    -
    -Several examples of using the bitmap API are available under the doc/examples/ directory in the source tree. Regression tests such as tests/hwloc/hwloc_bitmap*.c also make intensive use of this API.
    -

    Macro Definition Documentation

    - -

    ◆ hwloc_bitmap_foreach_begin

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    #define hwloc_bitmap_foreach_begin( id,
     bitmap 
    )
    -
    - -

    Loop macro iterating on bitmap bitmap.

    -

    The loop must start with hwloc_bitmap_foreach_begin() and end with hwloc_bitmap_foreach_end() followed by a terminating ';'.

    -

    id is the loop variable; it should be an unsigned int. The first iteration will set id to the lowest index in the bitmap. Successive iterations will iterate through, in order, all remaining indexes set in the bitmap. To be specific: each iteration will return a value for id such that hwloc_bitmap_isset(bitmap, id) is true.

    -

    The assert prevents the loop from being infinite if the bitmap is infinitely set.

    - -
    -
    - -

    ◆ hwloc_bitmap_foreach_end

    - -
    -
    - - - - - - - -
    #define hwloc_bitmap_foreach_end()
    -
    - -

    End of loop macro iterating on a bitmap.

    -

    Needs a terminating ';'.

    -
    See also
    hwloc_bitmap_foreach_begin()
    - -
    -
    -

    Typedef Documentation

    - -

    ◆ hwloc_bitmap_t

    - -
    -
    - - - - -
    typedef struct hwloc_bitmap_s* hwloc_bitmap_t
    -
    - -

    Set of bits represented as an opaque pointer to an internal bitmap.

    - -
    -
    - -

    ◆ hwloc_const_bitmap_t

    - -
    -
    - - - - -
    typedef const struct hwloc_bitmap_s* hwloc_const_bitmap_t
    -
    - -

    a non-modifiable hwloc_bitmap_t

    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_bitmap_allbut()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_allbut (hwloc_bitmap_t bitmap,
    unsigned id 
    )
    -
    - -

    Fill the bitmap and clear the index id.

    - -
    -
    - -

    ◆ hwloc_bitmap_alloc()

    - -
    -
    - - - - - - - - -
    hwloc_bitmap_t hwloc_bitmap_alloc (void )
    -
    - -

    Allocate a new empty bitmap.

    -
    Returns
    A valid bitmap or NULL.
    -

    The bitmap should be freed by a corresponding call to hwloc_bitmap_free().

    - -
    -
    - -

    ◆ hwloc_bitmap_alloc_full()

    - -
    -
    - - - - - - - - -
    hwloc_bitmap_t hwloc_bitmap_alloc_full (void )
    -
    - -

    Allocate a new full bitmap.

    - -
    -
    - -

    ◆ hwloc_bitmap_and()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_and (hwloc_bitmap_t res,
    hwloc_const_bitmap_t bitmap1,
    hwloc_const_bitmap_t bitmap2 
    )
    -
    - -

    And bitmaps bitmap1 and bitmap2 and store the result in bitmap res.

    -

    res can be the same as bitmap1 or bitmap2

    - -
    -
    - -

    ◆ hwloc_bitmap_andnot()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_andnot (hwloc_bitmap_t res,
    hwloc_const_bitmap_t bitmap1,
    hwloc_const_bitmap_t bitmap2 
    )
    -
    - -

    And bitmap bitmap1 and the negation of bitmap2 and store the result in bitmap res.

    -

    res can be the same as bitmap1 or bitmap2

    - -
    -
    - -

    ◆ hwloc_bitmap_asprintf()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_asprintf (char ** strp,
    hwloc_const_bitmap_t bitmap 
    )
    -
    - -

    Stringify a bitmap into a newly allocated string.

    -
    Returns
    -1 on error.
    - -
    -
    - -

    ◆ hwloc_bitmap_clr()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_clr (hwloc_bitmap_t bitmap,
    unsigned id 
    )
    -
    - -

    Remove index id from bitmap bitmap.

    - -
    -
    - -

    ◆ hwloc_bitmap_clr_range()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_clr_range (hwloc_bitmap_t bitmap,
    unsigned begin,
    int end 
    )
    -
    - -

    Remove indexes from begin to end in bitmap bitmap.

    -

    If end is -1, the range is infinite.

    - -
    -
    - -

    ◆ hwloc_bitmap_compare()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_compare (hwloc_const_bitmap_t bitmap1,
    hwloc_const_bitmap_t bitmap2 
    )
    -
    - -

    Compare bitmaps bitmap1 and bitmap2 in lexicographic order.

    -

    Lexicographic comparison of bitmaps, starting for their highest indexes. Compare last indexes first, then second, etc. The empty bitmap is considered lower than anything.

    -
    Returns
    -1 if bitmap1 is considered smaller than bitmap2.
    -
    -1 if bitmap1 is considered larger than bitmap2.
    -
    -0 if bitmaps are equal (contrary to hwloc_bitmap_compare_first()).
    -

    For instance comparing binary bitmaps 0011 and 0110 returns -1 (hence 0011 is considered smaller than 0110). Comparing 00101 and 01010 returns -1 too.

    -
    Note
    This is different from the non-existing hwloc_bitmap_compare_last() which would only compare the highest index of each bitmap.
    - -
    -
    - -

    ◆ hwloc_bitmap_compare_first()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_compare_first (hwloc_const_bitmap_t bitmap1,
    hwloc_const_bitmap_t bitmap2 
    )
    -
    - -

    Compare bitmaps bitmap1 and bitmap2 using their lowest index.

    -

    A bitmap is considered smaller if its least significant bit is smaller. The empty bitmap is considered higher than anything (because its least significant bit does not exist).

    -
    Returns
    -1 if bitmap1 is considered smaller than bitmap2.
    -
    -1 if bitmap1 is considered larger than bitmap2.
    -

    For instance comparing binary bitmaps 0011 and 0110 returns -1 (hence 0011 is considered smaller than 0110) because least significant bit of 0011 (0001) is smaller than least significant bit of 0110 (0010). Comparing 01001 and 00110 would also return -1 for the same reason.

    -
    Returns
    0 if bitmaps are considered equal, even if they are not strictly equal. They just need to have the same least significant bit. For instance, comparing binary bitmaps 0010 and 0110 returns 0 because they have the same least significant bit.
    - -
    -
    - -

    ◆ hwloc_bitmap_copy()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_copy (hwloc_bitmap_t dst,
    hwloc_const_bitmap_t src 
    )
    -
    - -

    Copy the contents of bitmap src into the already allocated bitmap dst.

    - -
    -
    - -

    ◆ hwloc_bitmap_dup()

    - -
    -
    - - - - - - - - -
    hwloc_bitmap_t hwloc_bitmap_dup (hwloc_const_bitmap_t bitmap)
    -
    - -

    Duplicate bitmap bitmap by allocating a new bitmap and copying bitmap contents.

    -

    If bitmap is NULL, NULL is returned.

    - -
    -
    - -

    ◆ hwloc_bitmap_fill()

    - -
    -
    - - - - - - - - -
    void hwloc_bitmap_fill (hwloc_bitmap_t bitmap)
    -
    - -

    Fill bitmap bitmap with all possible indexes (even if those objects don't exist or are otherwise unavailable)

    - -
    -
    - -

    ◆ hwloc_bitmap_first()

    - -
    -
    - - - - - - - - -
    int hwloc_bitmap_first (hwloc_const_bitmap_t bitmap)
    -
    - -

    Compute the first index (least significant bit) in bitmap bitmap.

    -
    Returns
    -1 if no index is set in bitmap.
    - -
    -
    - -

    ◆ hwloc_bitmap_first_unset()

    - -
    -
    - - - - - - - - -
    int hwloc_bitmap_first_unset (hwloc_const_bitmap_t bitmap)
    -
    - -

    Compute the first unset index (least significant bit) in bitmap bitmap.

    -
    Returns
    -1 if no index is unset in bitmap.
    - -
    -
    - -

    ◆ hwloc_bitmap_free()

    - -
    -
    - - - - - - - - -
    void hwloc_bitmap_free (hwloc_bitmap_t bitmap)
    -
    - -

    Free bitmap bitmap.

    -

    If bitmap is NULL, no operation is performed.

    - -
    -
    - -

    ◆ hwloc_bitmap_from_ith_ulong()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_from_ith_ulong (hwloc_bitmap_t bitmap,
    unsigned i,
    unsigned long mask 
    )
    -
    - -

    Setup bitmap bitmap from unsigned long mask used as i -th subset.

    - -
    -
    - -

    ◆ hwloc_bitmap_from_ulong()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_from_ulong (hwloc_bitmap_t bitmap,
    unsigned long mask 
    )
    -
    - -

    Setup bitmap bitmap from unsigned long mask.

    - -
    -
    - -

    ◆ hwloc_bitmap_from_ulongs()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_from_ulongs (hwloc_bitmap_t bitmap,
    unsigned nr,
    const unsigned long * masks 
    )
    -
    - -

    Setup bitmap bitmap from unsigned longs masks used as first nr subsets.

    - -
    -
    - -

    ◆ hwloc_bitmap_intersects()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_intersects (hwloc_const_bitmap_t bitmap1,
    hwloc_const_bitmap_t bitmap2 
    )
    -
    - -

    Test whether bitmaps bitmap1 and bitmap2 intersects.

    -
    Returns
    1 if bitmaps intersect, 0 otherwise.
    - -
    -
    - -

    ◆ hwloc_bitmap_isequal()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_isequal (hwloc_const_bitmap_t bitmap1,
    hwloc_const_bitmap_t bitmap2 
    )
    -
    - -

    Test whether bitmap bitmap1 is equal to bitmap bitmap2.

    -
    Returns
    1 if bitmaps are equal, 0 otherwise.
    - -
    -
    - -

    ◆ hwloc_bitmap_isfull()

    - -
    -
    - - - - - - - - -
    int hwloc_bitmap_isfull (hwloc_const_bitmap_t bitmap)
    -
    - -

    Test whether bitmap bitmap is completely full.

    -
    Returns
    1 if bitmap is full, 0 otherwise.
    -
    Note
    A full bitmap is always infinitely set.
    - -
    -
    - -

    ◆ hwloc_bitmap_isincluded()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_isincluded (hwloc_const_bitmap_t sub_bitmap,
    hwloc_const_bitmap_t super_bitmap 
    )
    -
    - -

    Test whether bitmap sub_bitmap is part of bitmap super_bitmap.

    -
    Returns
    1 if sub_bitmap is included in super_bitmap, 0 otherwise.
    -
    Note
    The empty bitmap is considered included in any other bitmap.
    - -
    -
    - -

    ◆ hwloc_bitmap_isset()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_isset (hwloc_const_bitmap_t bitmap,
    unsigned id 
    )
    -
    - -

    Test whether index id is part of bitmap bitmap.

    -
    Returns
    1 if the bit at index id is set in bitmap bitmap, 0 otherwise.
    - -
    -
    - -

    ◆ hwloc_bitmap_iszero()

    - -
    -
    - - - - - - - - -
    int hwloc_bitmap_iszero (hwloc_const_bitmap_t bitmap)
    -
    - -

    Test whether bitmap bitmap is empty.

    -
    Returns
    1 if bitmap is empty, 0 otherwise.
    - -
    -
    - -

    ◆ hwloc_bitmap_last()

    - -
    -
    - - - - - - - - -
    int hwloc_bitmap_last (hwloc_const_bitmap_t bitmap)
    -
    - -

    Compute the last index (most significant bit) in bitmap bitmap.

    -
    Returns
    -1 if no index is set in bitmap, or if bitmap is infinitely set.
    - -
    -
    - -

    ◆ hwloc_bitmap_last_unset()

    - -
    -
    - - - - - - - - -
    int hwloc_bitmap_last_unset (hwloc_const_bitmap_t bitmap)
    -
    - -

    Compute the last unset index (most significant bit) in bitmap bitmap.

    -
    Returns
    -1 if no index is unset in bitmap, or if bitmap is infinitely set.
    - -
    -
    - -

    ◆ hwloc_bitmap_list_asprintf()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_list_asprintf (char ** strp,
    hwloc_const_bitmap_t bitmap 
    )
    -
    - -

    Stringify a bitmap into a newly allocated list string.

    -
    Returns
    -1 on error.
    - -
    -
    - -

    ◆ hwloc_bitmap_list_snprintf()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_list_snprintf (char *restrict buf,
    size_t buflen,
    hwloc_const_bitmap_t bitmap 
    )
    -
    - -

    Stringify a bitmap in the list format.

    -

    Lists are comma-separated indexes or ranges. Ranges are dash separated indexes. The last range may not have an ending indexes if the bitmap is infinitely set.

    -

    Up to buflen characters may be written in buffer buf.

    -

    If buflen is 0, buf may safely be NULL.

    -
    Returns
    the number of characters that were actually written if not truncating, or that would have been written (not including the ending \0).
    - -
    -
    - -

    ◆ hwloc_bitmap_list_sscanf()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_list_sscanf (hwloc_bitmap_t bitmap,
    const char *restrict string 
    )
    -
    - -

    Parse a list string and stores it in bitmap bitmap.

    - -
    -
    - -

    ◆ hwloc_bitmap_next()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_next (hwloc_const_bitmap_t bitmap,
    int prev 
    )
    -
    - -

    Compute the next index in bitmap bitmap which is after index prev.

    -

    If prev is -1, the first index is returned.

    -
    Returns
    -1 if no index with higher index is set in bitmap.
    - -
    -
    - -

    ◆ hwloc_bitmap_next_unset()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_next_unset (hwloc_const_bitmap_t bitmap,
    int prev 
    )
    -
    - -

    Compute the next unset index in bitmap bitmap which is after index prev.

    -

    If prev is -1, the first unset index is returned.

    -
    Returns
    -1 if no index with higher index is unset in bitmap.
    - -
    -
    - -

    ◆ hwloc_bitmap_not()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_not (hwloc_bitmap_t res,
    hwloc_const_bitmap_t bitmap 
    )
    -
    - -

    Negate bitmap bitmap and store the result in bitmap res.

    -

    res can be the same as bitmap

    - -
    -
    - -

    ◆ hwloc_bitmap_nr_ulongs()

    - -
    -
    - - - - - - - - -
    int hwloc_bitmap_nr_ulongs (hwloc_const_bitmap_t bitmap)
    -
    - -

    Return the number of unsigned longs required for storing bitmap bitmap entirely.

    -

    This is the number of contiguous unsigned longs from the very first bit of the bitmap (even if unset) up to the last set bit. This is useful for knowing the nr parameter to pass to hwloc_bitmap_to_ulongs() (or which calls to hwloc_bitmap_to_ith_ulong() are needed) to entirely convert a bitmap into multiple unsigned longs.

    -

    When called on the output of hwloc_topology_get_topology_cpuset(), the returned number is large enough for all cpusets of the topology.

    -
    Returns
    -1 if bitmap is infinite.
    - -
    -
    - -

    ◆ hwloc_bitmap_only()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_only (hwloc_bitmap_t bitmap,
    unsigned id 
    )
    -
    - -

    Empty the bitmap bitmap and add bit id.

    - -
    -
    - -

    ◆ hwloc_bitmap_or()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_or (hwloc_bitmap_t res,
    hwloc_const_bitmap_t bitmap1,
    hwloc_const_bitmap_t bitmap2 
    )
    -
    - -

    Or bitmaps bitmap1 and bitmap2 and store the result in bitmap res.

    -

    res can be the same as bitmap1 or bitmap2

    - -
    -
    - -

    ◆ hwloc_bitmap_set()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_set (hwloc_bitmap_t bitmap,
    unsigned id 
    )
    -
    - -

    Add index id in bitmap bitmap.

    - -
    -
    - -

    ◆ hwloc_bitmap_set_ith_ulong()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_set_ith_ulong (hwloc_bitmap_t bitmap,
    unsigned i,
    unsigned long mask 
    )
    -
    - -

    Replace i -th subset of bitmap bitmap with unsigned long mask.

    - -
    -
    - -

    ◆ hwloc_bitmap_set_range()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_set_range (hwloc_bitmap_t bitmap,
    unsigned begin,
    int end 
    )
    -
    - -

    Add indexes from begin to end in bitmap bitmap.

    -

    If end is -1, the range is infinite.

    - -
    -
    - -

    ◆ hwloc_bitmap_singlify()

    - -
    -
    - - - - - - - - -
    int hwloc_bitmap_singlify (hwloc_bitmap_t bitmap)
    -
    - -

    Keep a single index among those set in bitmap bitmap.

    -

    May be useful before binding so that the process does not have a chance of migrating between multiple processors in the original mask. Instead of running the task on any PU inside the given CPU set, the operating system scheduler will be forced to run it on a single of these PUs. It avoids a migration overhead and cache-line ping-pongs between PUs.

    -
    Note
    This function is NOT meant to distribute multiple processes within a single CPU set. It always return the same single bit when called multiple times on the same input set. hwloc_distrib() may be used for generating CPU sets to distribute multiple tasks below a single multi-PU object.
    -
    -This function cannot be applied to an object set directly. It should be applied to a copy (which may be obtained with hwloc_bitmap_dup()).
    - -
    -
    - -

    ◆ hwloc_bitmap_snprintf()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_snprintf (char *restrict buf,
    size_t buflen,
    hwloc_const_bitmap_t bitmap 
    )
    -
    - -

    Stringify a bitmap.

    -

    Up to buflen characters may be written in buffer buf.

    -

    If buflen is 0, buf may safely be NULL.

    -
    Returns
    the number of characters that were actually written if not truncating, or that would have been written (not including the ending \0).
    - -
    -
    - -

    ◆ hwloc_bitmap_sscanf()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_sscanf (hwloc_bitmap_t bitmap,
    const char *restrict string 
    )
    -
    - -

    Parse a bitmap string and stores it in bitmap bitmap.

    - -
    -
    - -

    ◆ hwloc_bitmap_taskset_asprintf()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_taskset_asprintf (char ** strp,
    hwloc_const_bitmap_t bitmap 
    )
    -
    - -

    Stringify a bitmap into a newly allocated taskset-specific string.

    -
    Returns
    -1 on error.
    - -
    -
    - -

    ◆ hwloc_bitmap_taskset_snprintf()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_taskset_snprintf (char *restrict buf,
    size_t buflen,
    hwloc_const_bitmap_t bitmap 
    )
    -
    - -

    Stringify a bitmap in the taskset-specific format.

    -

    The taskset command manipulates bitmap strings that contain a single (possible very long) hexadecimal number starting with 0x.

    -

    Up to buflen characters may be written in buffer buf.

    -

    If buflen is 0, buf may safely be NULL.

    -
    Returns
    the number of characters that were actually written if not truncating, or that would have been written (not including the ending \0).
    - -
    -
    - -

    ◆ hwloc_bitmap_taskset_sscanf()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_taskset_sscanf (hwloc_bitmap_t bitmap,
    const char *restrict string 
    )
    -
    - -

    Parse a taskset-specific bitmap string and stores it in bitmap bitmap.

    - -
    -
    - -

    ◆ hwloc_bitmap_to_ith_ulong()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    unsigned long hwloc_bitmap_to_ith_ulong (hwloc_const_bitmap_t bitmap,
    unsigned i 
    )
    -
    - -

    Convert the i -th subset of bitmap bitmap into unsigned long mask.

    - -
    -
    - -

    ◆ hwloc_bitmap_to_ulong()

    - -
    -
    - - - - - - - - -
    unsigned long hwloc_bitmap_to_ulong (hwloc_const_bitmap_t bitmap)
    -
    - -

    Convert the beginning part of bitmap bitmap into unsigned long mask.

    - -
    -
    - -

    ◆ hwloc_bitmap_to_ulongs()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_to_ulongs (hwloc_const_bitmap_t bitmap,
    unsigned nr,
    unsigned long * masks 
    )
    -
    - -

    Convert the first nr subsets of bitmap bitmap into the array of nr unsigned long masks.

    -

    nr may be determined earlier with hwloc_bitmap_nr_ulongs().

    -
    Returns
    0
    - -
    -
    - -

    ◆ hwloc_bitmap_weight()

    - -
    -
    - - - - - - - - -
    int hwloc_bitmap_weight (hwloc_const_bitmap_t bitmap)
    -
    - -

    Compute the "weight" of bitmap bitmap (i.e., number of indexes that are in the bitmap).

    -
    Returns
    the number of indexes that are in the bitmap.
    -
    --1 if bitmap is infinitely set.
    - -
    -
    - -

    ◆ hwloc_bitmap_xor()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_xor (hwloc_bitmap_t res,
    hwloc_const_bitmap_t bitmap1,
    hwloc_const_bitmap_t bitmap2 
    )
    -
    - -

    Xor bitmaps bitmap1 and bitmap2 and store the result in bitmap res.

    -

    res can be the same as bitmap1 or bitmap2

    - -
    -
    - -

    ◆ hwloc_bitmap_zero()

    - -
    -
    - - - - - - - - -
    void hwloc_bitmap_zero (hwloc_bitmap_t bitmap)
    -
    - -

    Empty the bitmap bitmap.

    - -
    -
    -
    - - - - - - - -
    -
    -Enumerations | -Functions
    -
    -
    Exporting Topologies to XML
    -
    -
    - - - - -

    -Enumerations

    enum  hwloc_topology_export_xml_flags_e { HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1 - }
     
    - - - - - - - - - - - - - - - -

    -Functions

    int hwloc_topology_export_xml (hwloc_topology_t topology, const char *xmlpath, unsigned long flags)
     
    int hwloc_topology_export_xmlbuffer (hwloc_topology_t topology, char **xmlbuffer, int *buflen, unsigned long flags)
     
    void hwloc_free_xmlbuffer (hwloc_topology_t topology, char *xmlbuffer)
     
    void hwloc_topology_set_userdata_export_callback (hwloc_topology_t topology, void(*export_cb)(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj))
     
    int hwloc_export_obj_userdata (void *reserved, hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length)
     
    int hwloc_export_obj_userdata_base64 (void *reserved, hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length)
     
    void hwloc_topology_set_userdata_import_callback (hwloc_topology_t topology, void(*import_cb)(hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length))
     
    -

    Detailed Description

    -

    Enumeration Type Documentation

    - -

    ◆ hwloc_topology_export_xml_flags_e

    - -
    -
    - - - - -
    enum hwloc_topology_export_xml_flags_e
    -
    - -

    Flags for exporting XML topologies.

    -

    Flags to be given as a OR'ed set to hwloc_topology_export_xml().

    - - -
    Enumerator
    HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1 

    Export XML that is loadable by hwloc v1.x. However, the export may miss some details about the topology.

    -
    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_export_obj_userdata()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_export_obj_userdata (void * reserved,
    hwloc_topology_t topology,
    hwloc_obj_t obj,
    const char * name,
    const void * buffer,
    size_t length 
    )
    -
    - -

    Export some object userdata to XML.

    -

    This function may only be called from within the export() callback passed to hwloc_topology_set_userdata_export_callback(). It may be invoked one of multiple times to export some userdata to XML. The buffer content of length length is stored with optional name name.

    -

    When importing this XML file, the import() callback (if set) will be called exactly as many times as hwloc_export_obj_userdata() was called during export(). It will receive the corresponding name, buffer and length arguments.

    -

    reserved, topology and obj must be the first three parameters that were given to the export callback.

    -

    Only printable characters may be exported to XML string attributes. If a non-printable character is passed in name or buffer, the function returns -1 with errno set to EINVAL.

    -

    If exporting binary data, the application should first encode into printable characters only (or use hwloc_export_obj_userdata_base64()). It should also take care of portability issues if the export may be reimported on a different architecture.

    - -
    -
    - -

    ◆ hwloc_export_obj_userdata_base64()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_export_obj_userdata_base64 (void * reserved,
    hwloc_topology_t topology,
    hwloc_obj_t obj,
    const char * name,
    const void * buffer,
    size_t length 
    )
    -
    - -

    Encode and export some object userdata to XML.

    -

    This function is similar to hwloc_export_obj_userdata() but it encodes the input buffer into printable characters before exporting. On import, decoding is automatically performed before the data is given to the import() callback if any.

    -

    This function may only be called from within the export() callback passed to hwloc_topology_set_userdata_export_callback().

    -

    The function does not take care of portability issues if the export may be reimported on a different architecture.

    - -
    -
    - -

    ◆ hwloc_free_xmlbuffer()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    void hwloc_free_xmlbuffer (hwloc_topology_t topology,
    char * xmlbuffer 
    )
    -
    - -

    Free a buffer allocated by hwloc_topology_export_xmlbuffer()

    - -
    -
    - -

    ◆ hwloc_topology_export_xml()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_export_xml (hwloc_topology_t topology,
    const char * xmlpath,
    unsigned long flags 
    )
    -
    - -

    Export the topology into an XML file.

    -

    This file may be loaded later through hwloc_topology_set_xml().

    -

    By default, the latest export format is used, which means older hwloc releases (e.g. v1.x) will not be able to import it. Exporting to v1.x specific XML format is possible using flag HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1 but it may miss some details about the topology. If there is any chance that the exported file may ever be imported back by a process using hwloc 1.x, one should consider detecting it at runtime and using the corresponding export format.

    -

    flags is a OR'ed set of hwloc_topology_export_xml_flags_e.

    -
    Returns
    -1 if a failure occured.
    -
    Note
    See also hwloc_topology_set_userdata_export_callback() for exporting application-specific object userdata.
    -
    -The topology-specific userdata pointer is ignored when exporting to XML.
    -
    -Only printable characters may be exported to XML string attributes. Any other character, especially any non-ASCII character, will be silently dropped.
    -
    -If name is "-", the XML output is sent to the standard output.
    - -
    -
    - -

    ◆ hwloc_topology_export_xmlbuffer()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_export_xmlbuffer (hwloc_topology_t topology,
    char ** xmlbuffer,
    int * buflen,
    unsigned long flags 
    )
    -
    - -

    Export the topology into a newly-allocated XML memory buffer.

    -

    xmlbuffer is allocated by the callee and should be freed with hwloc_free_xmlbuffer() later in the caller.

    -

    This memory buffer may be loaded later through hwloc_topology_set_xmlbuffer().

    -

    By default, the latest export format is used, which means older hwloc releases (e.g. v1.x) will not be able to import it. Exporting to v1.x specific XML format is possible using flag HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1 but it may miss some details about the topology. If there is any chance that the exported buffer may ever be imported back by a process using hwloc 1.x, one should consider detecting it at runtime and using the corresponding export format.

    -

    The returned buffer ends with a \0 that is included in the returned length.

    -

    flags is a OR'ed set of hwloc_topology_export_xml_flags_e.

    -
    Returns
    -1 if a failure occured.
    -
    Note
    See also hwloc_topology_set_userdata_export_callback() for exporting application-specific object userdata.
    -
    -The topology-specific userdata pointer is ignored when exporting to XML.
    -
    -Only printable characters may be exported to XML string attributes. Any other character, especially any non-ASCII character, will be silently dropped.
    - -
    -
    - -

    ◆ hwloc_topology_set_userdata_export_callback()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    void hwloc_topology_set_userdata_export_callback (hwloc_topology_t topology,
    void(*)(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj) export_cb 
    )
    -
    - -

    Set the application-specific callback for exporting object userdata.

    -

    The object userdata pointer is not exported to XML by default because hwloc does not know what it contains.

    -

    This function lets applications set export_cb to a callback function that converts this opaque userdata into an exportable string.

    -

    export_cb is invoked during XML export for each object whose userdata pointer is not NULL. The callback should use hwloc_export_obj_userdata() or hwloc_export_obj_userdata_base64() to actually export something to XML (possibly multiple times per object).

    -

    export_cb may be set to NULL if userdata should not be exported to XML.

    -
    Note
    The topology-specific userdata pointer is ignored when exporting to XML.
    - -
    -
    - -

    ◆ hwloc_topology_set_userdata_import_callback()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    void hwloc_topology_set_userdata_import_callback (hwloc_topology_t topology,
    void(*)(hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length) import_cb 
    )
    -
    - -

    Set the application-specific callback for importing userdata.

    -

    On XML import, userdata is ignored by default because hwloc does not know how to store it in memory.

    -

    This function lets applications set import_cb to a callback function that will get the XML-stored userdata and store it in the object as expected by the application.

    -

    import_cb is called during hwloc_topology_load() as many times as hwloc_export_obj_userdata() was called during export. The topology is not entirely setup yet. Object attributes are ready to consult, but links between objects are not.

    -

    import_cb may be NULL if userdata should be ignored during import.

    -
    Note
    buffer contains length characters followed by a null byte ('\0').
    -
    -This function should be called before hwloc_topology_load().
    -
    -The topology-specific userdata pointer is ignored when importing from XML.
    - -
    -
    -
    - - - - - - - -
    -
    -Enumerations | -Functions
    -
    -
    Exporting Topologies to Synthetic
    -
    -
    - - - - -

    -Enumerations

    enum  hwloc_topology_export_synthetic_flags_e { HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_EXTENDED_TYPES -, HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_ATTRS -, HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_V1 -, HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_IGNORE_MEMORY - }
     
    - - - -

    -Functions

    int hwloc_topology_export_synthetic (hwloc_topology_t topology, char *buffer, size_t buflen, unsigned long flags)
     
    -

    Detailed Description

    -

    Enumeration Type Documentation

    - -

    ◆ hwloc_topology_export_synthetic_flags_e

    - -
    -
    - - - - -
    enum hwloc_topology_export_synthetic_flags_e
    -
    - -

    Flags for exporting synthetic topologies.

    -

    Flags to be given as a OR'ed set to hwloc_topology_export_synthetic().

    - - - - - -
    Enumerator
    HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_EXTENDED_TYPES 

    Export extended types such as L2dcache as basic types such as Cache.

    -

    This is required if loading the synthetic description with hwloc < 1.9.

    -
    HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_ATTRS 

    Do not export level attributes.

    -

    Ignore level attributes such as memory/cache sizes or PU indexes. This is required if loading the synthetic description with hwloc < 1.10.

    -
    HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_V1 

    Export the memory hierarchy as expected in hwloc 1.x.

    -

    Instead of attaching memory children to levels, export single NUMA node child as normal intermediate levels, when possible. This is required if loading the synthetic description with hwloc 1.x. However this may fail if some objects have multiple local NUMA nodes.

    -
    HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_IGNORE_MEMORY 

    Do not export memory information.

    -

    Only export the actual hierarchy of normal CPU-side objects and ignore where memory is attached. This is useful for when the hierarchy of CPUs is what really matters, but it behaves as if there was a single machine-wide NUMA node.

    -
    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_topology_export_synthetic()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_export_synthetic (hwloc_topology_t topology,
    char * buffer,
    size_t buflen,
    unsigned long flags 
    )
    -
    - -

    Export the topology as a synthetic string.

    -

    At most buflen characters will be written in buffer, including the terminating \0.

    -

    This exported string may be given back to hwloc_topology_set_synthetic().

    -

    flags is a OR'ed set of hwloc_topology_export_synthetic_flags_e.

    -
    Returns
    The number of characters that were written, not including the terminating \0.
    -
    --1 if the topology could not be exported, for instance if it is not symmetric.
    -
    Note
    I/O and Misc children are ignored, the synthetic string only describes normal children.
    -
    -A 1024-byte buffer should be large enough for exporting topologies in the vast majority of cases.
    - -
    -
    -
    - - - - - - - -
    -
    -Data Structures | -Enumerations | -Functions
    -
    -
    Retrieve distances between objects
    -
    -
    - - - - -

    -Data Structures

    struct  hwloc_distances_s
     
    - - - - - -

    -Enumerations

    enum  hwloc_distances_kind_e {
    -  HWLOC_DISTANCES_KIND_FROM_OS -, HWLOC_DISTANCES_KIND_FROM_USER -, HWLOC_DISTANCES_KIND_MEANS_LATENCY -, HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH -,
    -  HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES -
    - }
     
    enum  hwloc_distances_transform_e { HWLOC_DISTANCES_TRANSFORM_REMOVE_NULL -, HWLOC_DISTANCES_TRANSFORM_LINKS -, HWLOC_DISTANCES_TRANSFORM_MERGE_SWITCH_PORTS -, HWLOC_DISTANCES_TRANSFORM_TRANSITIVE_CLOSURE - }
     
    - - - - - - - - - - - - - - - -

    -Functions

    int hwloc_distances_get (hwloc_topology_t topology, unsigned *nr, struct hwloc_distances_s **distances, unsigned long kind, unsigned long flags)
     
    int hwloc_distances_get_by_depth (hwloc_topology_t topology, int depth, unsigned *nr, struct hwloc_distances_s **distances, unsigned long kind, unsigned long flags)
     
    int hwloc_distances_get_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned *nr, struct hwloc_distances_s **distances, unsigned long kind, unsigned long flags)
     
    int hwloc_distances_get_by_name (hwloc_topology_t topology, const char *name, unsigned *nr, struct hwloc_distances_s **distances, unsigned long flags)
     
    const char * hwloc_distances_get_name (hwloc_topology_t topology, struct hwloc_distances_s *distances)
     
    void hwloc_distances_release (hwloc_topology_t topology, struct hwloc_distances_s *distances)
     
    int hwloc_distances_transform (hwloc_topology_t topology, struct hwloc_distances_s *distances, enum hwloc_distances_transform_e transform, void *transform_attr, unsigned long flags)
     
    -

    Detailed Description

    -

    Enumeration Type Documentation

    - -

    ◆ hwloc_distances_kind_e

    - -
    -
    - - - - -
    enum hwloc_distances_kind_e
    -
    - -

    Kinds of distance matrices.

    -

    The kind attribute of struct hwloc_distances_s is a OR'ed set of kinds.

    -

    A kind of format HWLOC_DISTANCES_KIND_FROM_* specifies where the distance information comes from, if known.

    -

    A kind of format HWLOC_DISTANCES_KIND_MEANS_* specifies whether values are latencies or bandwidths, if applicable.

    - - - - - - -
    Enumerator
    HWLOC_DISTANCES_KIND_FROM_OS 

    These distances were obtained from the operating system or hardware.

    -
    HWLOC_DISTANCES_KIND_FROM_USER 

    These distances were provided by the user.

    -
    HWLOC_DISTANCES_KIND_MEANS_LATENCY 

    Distance values are similar to latencies between objects. Values are smaller for closer objects, hence minimal on the diagonal of the matrix (distance between an object and itself). It could also be the number of network hops between objects, etc.

    -
    HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH 

    Distance values are similar to bandwidths between objects. Values are higher for closer objects, hence maximal on the diagonal of the matrix (distance between an object and itself). Such values are currently ignored for distance-based grouping.

    -
    HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES 

    This distances structure covers objects of different types. This may apply to the "NVLinkBandwidth" structure in presence of a NVSwitch or POWER processor NVLink port.

    -
    - -
    -
    - -

    ◆ hwloc_distances_transform_e

    - -
    -
    - - - - -
    enum hwloc_distances_transform_e
    -
    - -

    Transformations of distances structures.

    - - - - - -
    Enumerator
    HWLOC_DISTANCES_TRANSFORM_REMOVE_NULL 

    Remove NULL objects from the distances structure.

    -

    Every object that was replaced with NULL in the objs array is removed and the values array is updated accordingly.

    -

    At least 2 objects must remain, otherwise hwloc_distances_transform() will return -1 with errno set to EINVAL.

    -

    kind will be updated with or without HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES according to the remaining objects.

    -
    HWLOC_DISTANCES_TRANSFORM_LINKS 

    Replace bandwidth values with a number of links.

    -

    Usually all values will be either 0 (no link) or 1 (one link). However some matrices could get larger values if some pairs of peers are connected by different numbers of links.

    -

    Values on the diagonal are set to 0.

    -

    This transformation only applies to bandwidth matrices.

    -
    HWLOC_DISTANCES_TRANSFORM_MERGE_SWITCH_PORTS 

    Merge switches with multiple ports into a single object. This currently only applies to NVSwitches where GPUs seem connected to different separate switch ports in the NVLinkBandwidth matrix. This transformation will replace all of them with the same port connected to all GPUs. Other ports are removed by applying HWLOC_DISTANCES_TRANSFORM_REMOVE_NULL internally.

    -
    HWLOC_DISTANCES_TRANSFORM_TRANSITIVE_CLOSURE 

    Apply a transitive closure to the matrix to connect objects across switches. This currently only applies to GPUs and NVSwitches in the NVLinkBandwidth matrix. All pairs of GPUs will be reported as directly connected.

    -
    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_distances_get()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_distances_get (hwloc_topology_t topology,
    unsigned * nr,
    struct hwloc_distances_s ** distances,
    unsigned long kind,
    unsigned long flags 
    )
    -
    - -

    Retrieve distance matrices.

    -

    Retrieve distance matrices from the topology into the distances array.

    -

    flags is currently unused, should be 0.

    -

    kind serves as a filter. If 0, all distance matrices are returned. If it contains some HWLOC_DISTANCES_KIND_FROM_*, only distance matrices whose kind matches one of these are returned. If it contains some HWLOC_DISTANCES_KIND_MEANS_*, only distance matrices whose kind matches one of these are returned.

    -

    On input, nr points to the number of distance matrices that may be stored in distances. On output, nr points to the number of distance matrices that were actually found, even if some of them couldn't be stored in distances. Distance matrices that couldn't be stored are ignored, but the function still returns success (0). The caller may find out by comparing the value pointed by nr before and after the function call.

    -

    Each distance matrix returned in the distances array should be released by the caller using hwloc_distances_release().

    - -
    -
    - -

    ◆ hwloc_distances_get_by_depth()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_distances_get_by_depth (hwloc_topology_t topology,
    int depth,
    unsigned * nr,
    struct hwloc_distances_s ** distances,
    unsigned long kind,
    unsigned long flags 
    )
    -
    - -

    Retrieve distance matrices for object at a specific depth in the topology.

    -

    Identical to hwloc_distances_get() with the additional depth filter.

    - -
    -
    - -

    ◆ hwloc_distances_get_by_name()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_distances_get_by_name (hwloc_topology_t topology,
    const char * name,
    unsigned * nr,
    struct hwloc_distances_s ** distances,
    unsigned long flags 
    )
    -
    - -

    Retrieve a distance matrix with the given name.

    -

    Usually only one distances structure may match a given name.

    -

    The name of the most common structure is "NUMALatency". Others include "XGMIBandwidth", "XGMIHops", "XeLinkBandwidth", and "NVLinkBandwidth".

    - -
    -
    - -

    ◆ hwloc_distances_get_by_type()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_distances_get_by_type (hwloc_topology_t topology,
    hwloc_obj_type_t type,
    unsigned * nr,
    struct hwloc_distances_s ** distances,
    unsigned long kind,
    unsigned long flags 
    )
    -
    - -

    Retrieve distance matrices for object of a specific type.

    -

    Identical to hwloc_distances_get() with the additional type filter.

    - -
    -
    - -

    ◆ hwloc_distances_get_name()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    const char* hwloc_distances_get_name (hwloc_topology_t topology,
    struct hwloc_distances_s * distances 
    )
    -
    - -

    Get a description of what a distances structure contains.

    -

    For instance "NUMALatency" for hardware-provided NUMA distances (ACPI SLIT), or NULL if unknown.

    - -
    -
    - -

    ◆ hwloc_distances_release()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    void hwloc_distances_release (hwloc_topology_t topology,
    struct hwloc_distances_s * distances 
    )
    -
    - -

    Release a distance matrix structure previously returned by hwloc_distances_get().

    -
    Note
    This function is not required if the structure is removed with hwloc_distances_release_remove().
    - -
    -
    - -

    ◆ hwloc_distances_transform()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_distances_transform (hwloc_topology_t topology,
    struct hwloc_distances_s * distances,
    enum hwloc_distances_transform_e transform,
    void * transform_attr,
    unsigned long flags 
    )
    -
    - -

    Apply a transformation to a distances structure.

    -

    Modify a distances structure that was previously obtained with hwloc_distances_get() or one of its variants.

    -

    This modifies the local copy of the distances structures but does not modify the distances information stored inside the topology (retrieved by another call to hwloc_distances_get() or exported to XML). To do so, one should add a new distances structure with same name, kind, objects and values (see Add distances between objects) and then remove this old one with hwloc_distances_release_remove().

    -

    transform must be one of the transformations listed in hwloc_distances_transform_e.

    -

    These transformations may modify the contents of the objs or values arrays.

    -

    transform_attr must be NULL for now.

    -

    flags must be 0 for now.

    -
    Note
    Objects in distances array objs may be directly modified in place without using hwloc_distances_transform(). One may use hwloc_get_obj_with_same_locality() to easily convert between similar objects of different types.
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    -
    Helpers for consulting distance matrices
    -
    -
    - - - - - - -

    -Functions

    static int hwloc_distances_obj_index (struct hwloc_distances_s *distances, hwloc_obj_t obj)
     
    static int hwloc_distances_obj_pair_values (struct hwloc_distances_s *distances, hwloc_obj_t obj1, hwloc_obj_t obj2, hwloc_uint64_t *value1to2, hwloc_uint64_t *value2to1)
     
    -

    Detailed Description

    -

    Function Documentation

    - -

    ◆ hwloc_distances_obj_index()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static int hwloc_distances_obj_index (struct hwloc_distances_s * distances,
    hwloc_obj_t obj 
    )
    -     		-inlinestatic
    -
    - -

    Find the index of an object in a distances structure.

    -
    Returns
    -1 if object obj is not involved in structure distances.
    - -
    -
    - -

    ◆ hwloc_distances_obj_pair_values()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_distances_obj_pair_values (struct hwloc_distances_s * distances,
    hwloc_obj_t obj1,
    hwloc_obj_t obj2,
    hwloc_uint64_t * value1to2,
    hwloc_uint64_t * value2to1 
    )
    -     		-inlinestatic
    -
    - -

    Find the values between two objects in a distance matrices.

    -

    The distance from obj1 to obj2 is stored in the value pointed by value1to2 and reciprocally.

    -
    Returns
    -1 if object obj1 or obj2 is not involved in structure distances.
    - -
    -
    -
    - - - - - - - -
    -
    -Typedefs | -Enumerations | -Functions
    -
    -
    Add distances between objects
    -
    -
    - - - - -

    -Typedefs

    typedef void * hwloc_distances_add_handle_t
     
    - - - -

    -Enumerations

    enum  hwloc_distances_add_flag_e { HWLOC_DISTANCES_ADD_FLAG_GROUP -, HWLOC_DISTANCES_ADD_FLAG_GROUP_INACCURATE - }
     
    - - - - - - - -

    -Functions

    hwloc_distances_add_handle_t hwloc_distances_add_create (hwloc_topology_t topology, const char *name, unsigned long kind, unsigned long flags)
     
    int hwloc_distances_add_values (hwloc_topology_t topology, hwloc_distances_add_handle_t handle, unsigned nbobjs, hwloc_obj_t *objs, hwloc_uint64_t *values, unsigned long flags)
     
    int hwloc_distances_add_commit (hwloc_topology_t topology, hwloc_distances_add_handle_t handle, unsigned long flags)
     
    -

    Detailed Description

    -

    The usual way to add distances is:

    hwloc_distances_add_handle_t handle;
    -
    int err = -1;
    -
    handle = hwloc_distances_add_create(topology, "name", kind, 0);
    -
    if (handle) {
    -
    err = hwloc_distances_add_values(topology, handle, nbobjs, objs, values, 0);
    -
    if (!err)
    -
    err = hwloc_distances_add_commit(topology, handle, flags);
    -
    }
    -
    hwloc_distances_add_commit
    int hwloc_distances_add_commit(hwloc_topology_t topology, hwloc_distances_add_handle_t handle, unsigned long flags)
    Commit a new distances structure.
    -
    hwloc_distances_add_handle_t
    void * hwloc_distances_add_handle_t
    Handle to a new distances structure during its addition to the topology.
    Definition: distances.h:331
    -
    hwloc_distances_add_create
    hwloc_distances_add_handle_t hwloc_distances_add_create(hwloc_topology_t topology, const char *name, unsigned long kind, unsigned long flags)
    Create a new empty distances structure.
    -
    hwloc_distances_add_values
    int hwloc_distances_add_values(hwloc_topology_t topology, hwloc_distances_add_handle_t handle, unsigned nbobjs, hwloc_obj_t *objs, hwloc_uint64_t *values, unsigned long flags)
    Specify the objects and values in a new empty distances structure.
    -

    If err is 0 at the end, then addition was successful.

    -

    Typedef Documentation

    - -

    ◆ hwloc_distances_add_handle_t

    - -
    -
    - - - - -
    typedef void* hwloc_distances_add_handle_t
    -
    - -

    Handle to a new distances structure during its addition to the topology.

    - -
    -
    -

    Enumeration Type Documentation

    - -

    ◆ hwloc_distances_add_flag_e

    - -
    -
    - - - - -
    enum hwloc_distances_add_flag_e
    -
    - -

    Flags for adding a new distances to a topology.

    - - - -
    Enumerator
    HWLOC_DISTANCES_ADD_FLAG_GROUP 

    Try to group objects based on the newly provided distance information. This is ignored for distances between objects of different types.

    -
    HWLOC_DISTANCES_ADD_FLAG_GROUP_INACCURATE 

    If grouping, consider the distance values as inaccurate and relax the comparisons during the grouping algorithms. The actual accuracy may be modified through the HWLOC_GROUPING_ACCURACY environment variable (see Environment Variables).

    -
    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_distances_add_commit()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_distances_add_commit (hwloc_topology_t topology,
    hwloc_distances_add_handle_t handle,
    unsigned long flags 
    )
    -
    - -

    Commit a new distances structure.

    -

    This function finalizes the distances structure and inserts in it the topology.

    -

    Parameter handle was previously returned by hwloc_distances_add_create(). Then objects and values were specified with hwloc_distances_add_values().

    -

    flags configures the behavior of the function using an optional OR'ed set of hwloc_distances_add_flag_e. It may be used to request the grouping of existing objects based on distances.

    -

    On error, the temporary distances structure and its content are destroyed.

    -
    Returns
    0 on success.
    -
    --1 on error.
    - -
    -
    - -

    ◆ hwloc_distances_add_create()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    hwloc_distances_add_handle_t hwloc_distances_add_create (hwloc_topology_t topology,
    const char * name,
    unsigned long kind,
    unsigned long flags 
    )
    -
    - -

    Create a new empty distances structure.

    -

    Create an empty distances structure to be filled with hwloc_distances_add_values() and then committed with hwloc_distances_add_commit().

    -

    Parameter name is optional, it may be NULL. Otherwise, it will be copied internally and may later be freed by the caller.

    -

    kind specifies the kind of distance as a OR'ed set of hwloc_distances_kind_e. Kind HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES will be automatically set according to objects having different types in hwloc_distances_add_values().

    -

    flags must be 0 for now.

    -
    Returns
    A hwloc_distances_add_handle_t that should then be passed to hwloc_distances_add_values() and hwloc_distances_add_commit().
    -
    -NULL on error.
    - -
    -
    - -

    ◆ hwloc_distances_add_values()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_distances_add_values (hwloc_topology_t topology,
    hwloc_distances_add_handle_t handle,
    unsigned nbobjs,
    hwloc_obj_t * objs,
    hwloc_uint64_t * values,
    unsigned long flags 
    )
    -
    - -

    Specify the objects and values in a new empty distances structure.

    -

    Specify the objects and values for a new distances structure that was returned as a handle by hwloc_distances_add_create(). The structure must then be committed with hwloc_distances_add_commit().

    -

    The number of objects is nbobjs and the array of objects is objs. Distance values are stored as a one-dimension array in values. The distance from object i to object j is in slot i*nbobjs+j.

    -

    nbobjs must be at least 2.

    -

    Arrays objs and values will be copied internally, they may later be freed by the caller.

    -

    On error, the temporary distances structure and its content are destroyed.

    -

    flags must be 0 for now.

    -
    Returns
    0 on success.
    -
    --1 on error.
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    -
    Remove distances between objects
    -
    -
    - - - - - - - - - - -

    -Functions

    int hwloc_distances_remove (hwloc_topology_t topology)
     
    int hwloc_distances_remove_by_depth (hwloc_topology_t topology, int depth)
     
    static int hwloc_distances_remove_by_type (hwloc_topology_t topology, hwloc_obj_type_t type)
     
    int hwloc_distances_release_remove (hwloc_topology_t topology, struct hwloc_distances_s *distances)
     
    -

    Detailed Description

    -

    Function Documentation

    - -

    ◆ hwloc_distances_release_remove()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_distances_release_remove (hwloc_topology_t topology,
    struct hwloc_distances_s * distances 
    )
    -
    - -

    Release and remove the given distance matrice from the topology.

    -

    This function includes a call to hwloc_distances_release().

    - -
    -
    - -

    ◆ hwloc_distances_remove()

    - -
    -
    - - - - - - - - -
    int hwloc_distances_remove (hwloc_topology_t topology)
    -
    - -

    Remove all distance matrices from a topology.

    -

    Remove all distance matrices, either provided by the user or gathered through the OS.

    -

    If these distances were used to group objects, these additional Group objects are not removed from the topology.

    - -
    -
    - -

    ◆ hwloc_distances_remove_by_depth()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_distances_remove_by_depth (hwloc_topology_t topology,
    int depth 
    )
    -
    - -

    Remove distance matrices for objects at a specific depth in the topology.

    -

    Identical to hwloc_distances_remove() but only applies to one level of the topology.

    - -
    -
    - -

    ◆ hwloc_distances_remove_by_type()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static int hwloc_distances_remove_by_type (hwloc_topology_t topology,
    hwloc_obj_type_t type 
    )
    -     		-inlinestatic
    -
    - -

    Remove distance matrices for objects of a specific type in the topology.

    -

    Identical to hwloc_distances_remove() but only applies to one level of the topology.

    - -
    -
    -
    - - - - - - - -
    -
    -Data Structures | -Typedefs | -Enumerations | -Functions
    -
    -
    Comparing memory node attributes for finding where to allocate on
    -
    -
    - - - - -

    -Data Structures

    struct  hwloc_location
     
    - - - -

    -Typedefs

    typedef unsigned hwloc_memattr_id_t
     
    - - - - - - - -

    -Enumerations

    enum  hwloc_memattr_id_e {
    -  HWLOC_MEMATTR_ID_CAPACITY -, HWLOC_MEMATTR_ID_LOCALITY -, HWLOC_MEMATTR_ID_BANDWIDTH -, HWLOC_MEMATTR_ID_READ_BANDWIDTH -,
    -  HWLOC_MEMATTR_ID_WRITE_BANDWIDTH -, HWLOC_MEMATTR_ID_LATENCY -, HWLOC_MEMATTR_ID_READ_LATENCY -, HWLOC_MEMATTR_ID_WRITE_LATENCY -,
    -  HWLOC_MEMATTR_ID_MAX -
    - }
     
    enum  hwloc_location_type_e { HWLOC_LOCATION_TYPE_CPUSET -, HWLOC_LOCATION_TYPE_OBJECT - }
     
    enum  hwloc_local_numanode_flag_e { HWLOC_LOCAL_NUMANODE_FLAG_LARGER_LOCALITY -, HWLOC_LOCAL_NUMANODE_FLAG_SMALLER_LOCALITY -, HWLOC_LOCAL_NUMANODE_FLAG_ALL - }
     
    - - - - - - - - - - - -

    -Functions

    int hwloc_memattr_get_by_name (hwloc_topology_t topology, const char *name, hwloc_memattr_id_t *id)
     
    int hwloc_get_local_numanode_objs (hwloc_topology_t topology, struct hwloc_location *location, unsigned *nr, hwloc_obj_t *nodes, unsigned long flags)
     
    int hwloc_memattr_get_value (hwloc_topology_t topology, hwloc_memattr_id_t attribute, hwloc_obj_t target_node, struct hwloc_location *initiator, unsigned long flags, hwloc_uint64_t *value)
     
    int hwloc_memattr_get_best_target (hwloc_topology_t topology, hwloc_memattr_id_t attribute, struct hwloc_location *initiator, unsigned long flags, hwloc_obj_t *best_target, hwloc_uint64_t *value)
     
    int hwloc_memattr_get_best_initiator (hwloc_topology_t topology, hwloc_memattr_id_t attribute, hwloc_obj_t target, unsigned long flags, struct hwloc_location *best_initiator, hwloc_uint64_t *value)
     
    -

    Detailed Description

    -

    Platforms with heterogeneous memory require ways to decide whether a buffer should be allocated on "fast" memory (such as HBM), "normal" memory (DDR) or even "slow" but large-capacity memory (non-volatile memory). These memory nodes are called "Targets" while the CPU accessing them is called the "Initiator". Access performance depends on their locality (NUMA platforms) as well as the intrinsic performance of the targets (heterogeneous platforms).

    -

    The following attributes describe the performance of memory accesses from an Initiator to a memory Target, for instance their latency or bandwidth. Initiators performing these memory accesses are usually some PUs or Cores (described as a CPU set). Hence a Core may choose where to allocate a memory buffer by comparing the attributes of different target memory nodes nearby.

    -

    There are also some attributes that are system-wide. Their value does not depend on a specific initiator performing an access. The memory node Capacity is an example of such attribute without initiator.

    -

    One way to use this API is to start with a cpuset describing the Cores where a program is bound. The best target NUMA node for allocating memory in this program on these Cores may be obtained by passing this cpuset as an initiator to hwloc_memattr_get_best_target() with the relevant memory attribute. For instance, if the code is latency limited, use the Latency attribute.

    -

    A more flexible approach consists in getting the list of local NUMA nodes by passing this cpuset to hwloc_get_local_numanode_objs(). Attribute values for these nodes, if any, may then be obtained with hwloc_memattr_get_value() and manually compared with the desired criteria.

    -
    See also
    An example is available in doc/examples/memory-attributes.c in the source tree.
    -
    Note
    The API also supports specific objects as initiator, but it is currently not used internally by hwloc. Users may for instance use it to provide custom performance values for host memory accesses performed by GPUs.
    -
    -The interface actually also accepts targets that are not NUMA nodes.
    -

    Typedef Documentation

    - -

    ◆ hwloc_memattr_id_t

    - -
    -
    - - - - -
    typedef unsigned hwloc_memattr_id_t
    -
    - -

    A memory attribute identifier. May be either one of hwloc_memattr_id_e or a new id returned by hwloc_memattr_register().

    - -
    -
    -

    Enumeration Type Documentation

    - -

    ◆ hwloc_local_numanode_flag_e

    - -
    -
    - - - - -
    enum hwloc_local_numanode_flag_e
    -
    - -

    Flags for selecting target NUMA nodes.

    - - - - -
    Enumerator
    HWLOC_LOCAL_NUMANODE_FLAG_LARGER_LOCALITY 

    Select NUMA nodes whose locality is larger than the given cpuset. For instance, if a single PU (or its cpuset) is given in initiator, select all nodes close to the package that contains this PU.

    -
    HWLOC_LOCAL_NUMANODE_FLAG_SMALLER_LOCALITY 

    Select NUMA nodes whose locality is smaller than the given cpuset. For instance, if a package (or its cpuset) is given in initiator, also select nodes that are attached to only a half of that package.

    -
    HWLOC_LOCAL_NUMANODE_FLAG_ALL 

    Select all NUMA nodes in the topology. The initiator initiator is ignored.

    -
    - -
    -
    - -

    ◆ hwloc_location_type_e

    - -
    -
    - - - - -
    enum hwloc_location_type_e
    -
    - -

    Type of location.

    - - - -
    Enumerator
    HWLOC_LOCATION_TYPE_CPUSET 

    Location is given as a cpuset, in the location cpuset union field.

    -
    HWLOC_LOCATION_TYPE_OBJECT 

    Location is given as an object, in the location object union field.

    -
    - -
    -
    - -

    ◆ hwloc_memattr_id_e

    - -
    -
    - - - - -
    enum hwloc_memattr_id_e
    -
    - -

    Memory node attributes.

    - - - - - - - - - -
    Enumerator
    HWLOC_MEMATTR_ID_CAPACITY 

    The "Capacity" is returned in bytes (local_memory attribute in objects).

    -

    Best capacity nodes are nodes with higher capacity.

    -

    No initiator is involved when looking at this attribute. The corresponding attribute flags are HWLOC_MEMATTR_FLAG_HIGHER_FIRST.

    -
    HWLOC_MEMATTR_ID_LOCALITY 

    The "Locality" is returned as the number of PUs in that locality (e.g. the weight of its cpuset).

    -

    Best locality nodes are nodes with smaller locality (nodes that are local to very few PUs). Poor locality nodes are nodes with larger locality (nodes that are local to the entire machine).

    -

    No initiator is involved when looking at this attribute. The corresponding attribute flags are HWLOC_MEMATTR_FLAG_HIGHER_FIRST.

    -
    HWLOC_MEMATTR_ID_BANDWIDTH 

    The "Bandwidth" is returned in MiB/s, as seen from the given initiator location.

    -

    Best bandwidth nodes are nodes with higher bandwidth.

    -

    The corresponding attribute flags are HWLOC_MEMATTR_FLAG_HIGHER_FIRST and HWLOC_MEMATTR_FLAG_NEED_INITIATOR.

    -

    This is the average bandwidth for read and write accesses. If the platform provides individual read and write bandwidths but no explicit average value, hwloc computes and returns the average.

    -
    HWLOC_MEMATTR_ID_READ_BANDWIDTH 

    The "ReadBandwidth" is returned in MiB/s, as seen from the given initiator location.

    -

    Best bandwidth nodes are nodes with higher bandwidth.

    -

    The corresponding attribute flags are HWLOC_MEMATTR_FLAG_HIGHER_FIRST and HWLOC_MEMATTR_FLAG_NEED_INITIATOR.

    -
    HWLOC_MEMATTR_ID_WRITE_BANDWIDTH 

    The "WriteBandwidth" is returned in MiB/s, as seen from the given initiator location.

    -

    Best bandwidth nodes are nodes with higher bandwidth.

    -

    The corresponding attribute flags are HWLOC_MEMATTR_FLAG_HIGHER_FIRST and HWLOC_MEMATTR_FLAG_NEED_INITIATOR.

    -
    HWLOC_MEMATTR_ID_LATENCY 

    The "Latency" is returned as nanoseconds, as seen from the given initiator location.

    -

    Best latency nodes are nodes with smaller latency.

    -

    The corresponding attribute flags are HWLOC_MEMATTR_FLAG_LOWER_FIRST and HWLOC_MEMATTR_FLAG_NEED_INITIATOR.

    -

    This is the average latency for read and write accesses. If the platform provides individual read and write latencies but no explicit average value, hwloc computes and returns the average.

    -
    HWLOC_MEMATTR_ID_READ_LATENCY 

    The "ReadLatency" is returned as nanoseconds, as seen from the given initiator location.

    -

    Best latency nodes are nodes with smaller latency.

    -

    The corresponding attribute flags are HWLOC_MEMATTR_FLAG_LOWER_FIRST and HWLOC_MEMATTR_FLAG_NEED_INITIATOR.

    -
    HWLOC_MEMATTR_ID_WRITE_LATENCY 

    The "WriteLatency" is returned as nanoseconds, as seen from the given initiator location.

    -

    Best latency nodes are nodes with smaller latency.

    -

    The corresponding attribute flags are HWLOC_MEMATTR_FLAG_LOWER_FIRST and HWLOC_MEMATTR_FLAG_NEED_INITIATOR.

    -
    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_get_local_numanode_objs()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_get_local_numanode_objs (hwloc_topology_t topology,
    struct hwloc_location * location,
    unsigned * nr,
    hwloc_obj_t * nodes,
    unsigned long flags 
    )
    -
    - -

    Return an array of local NUMA nodes.

    -

    By default only select the NUMA nodes whose locality is exactly the given location. More nodes may be selected if additional flags are given as a OR'ed set of hwloc_local_numanode_flag_e.

    -

    If location is given as an explicit object, its CPU set is used to find NUMA nodes with the corresponding locality. If the object does not have a CPU set (e.g. I/O object), the CPU parent (where the I/O object is attached) is used.

    -

    On input, nr points to the number of nodes that may be stored in the nodes array. On output, nr will be changed to the number of stored nodes, or the number of nodes that would have been stored if there were enough room.

    -
    Note
    Some of these NUMA nodes may not have any memory attribute values and hence not be reported as actual targets in other functions.
    -
    -The number of NUMA nodes in the topology (obtained by hwloc_bitmap_weight() on the root object nodeset) may be used to allocate the nodes array.
    -
    -When an object CPU set is given as locality, for instance a Package, and when flags contain both HWLOC_LOCAL_NUMANODE_FLAG_LARGER_LOCALITY and HWLOC_LOCAL_NUMANODE_FLAG_SMALLER_LOCALITY, the returned array corresponds to the nodeset of that object.
    - -
    -
    - -

    ◆ hwloc_memattr_get_best_initiator()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_memattr_get_best_initiator (hwloc_topology_t topology,
    hwloc_memattr_id_t attribute,
    hwloc_obj_t target,
    unsigned long flags,
    struct hwloc_location * best_initiator,
    hwloc_uint64_t * value 
    )
    -
    - -

    Return the best initiator for the given attribute and target NUMA node.

    -

    If the attribute does not relate to a specific initiator (it does not have the flag HWLOC_MEMATTR_FLAG_NEED_INITIATOR), -1 is returned and errno is set to EINVAL.

    -

    If value is non NULL, the corresponding value is returned there.

    -

    If multiple initiators have the same attribute values, only one is returned (and there is no way to clarify how that one is chosen). Applications that want to detect initiators with identical/similar values, or that want to look at values for multiple attributes, should rather get all values using hwloc_memattr_get_value() and manually select the initiator they consider the best.

    -

    The returned initiator should not be modified or freed, it belongs to the topology.

    -

    flags must be 0 for now.

    -

    If there are no matching initiators, -1 is returned with errno set to ENOENT;

    - -
    -
    - -

    ◆ hwloc_memattr_get_best_target()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_memattr_get_best_target (hwloc_topology_t topology,
    hwloc_memattr_id_t attribute,
    struct hwloc_location * initiator,
    unsigned long flags,
    hwloc_obj_t * best_target,
    hwloc_uint64_t * value 
    )
    -
    - -

    Return the best target NUMA node for the given attribute and initiator.

    -

    If the attribute does not relate to a specific initiator (it does not have the flag HWLOC_MEMATTR_FLAG_NEED_INITIATOR), location initiator is ignored and may be NULL.

    -

    If value is non NULL, the corresponding value is returned there.

    -

    If multiple targets have the same attribute values, only one is returned (and there is no way to clarify how that one is chosen). Applications that want to detect targets with identical/similar values, or that want to look at values for multiple attributes, should rather get all values using hwloc_memattr_get_value() and manually select the target they consider the best.

    -

    flags must be 0 for now.

    -

    If there are no matching targets, -1 is returned with errno set to ENOENT;

    -
    Note
    The initiator initiator should be of type HWLOC_LOCATION_TYPE_CPUSET when refering to accesses performed by CPU cores. HWLOC_LOCATION_TYPE_OBJECT is currently unused internally by hwloc, but users may for instance use it to provide custom information about host memory accesses performed by GPUs.
    - -
    -
    - -

    ◆ hwloc_memattr_get_by_name()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_memattr_get_by_name (hwloc_topology_t topology,
    const char * name,
    hwloc_memattr_id_t * id 
    )
    -
    - -

    Return the identifier of the memory attribute with the given name.

    - -
    -
    - -

    ◆ hwloc_memattr_get_value()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_memattr_get_value (hwloc_topology_t topology,
    hwloc_memattr_id_t attribute,
    hwloc_obj_t target_node,
    struct hwloc_location * initiator,
    unsigned long flags,
    hwloc_uint64_t * value 
    )
    -
    - -

    Return an attribute value for a specific target NUMA node.

    -

    If the attribute does not relate to a specific initiator (it does not have the flag HWLOC_MEMATTR_FLAG_NEED_INITIATOR), location initiator is ignored and may be NULL.

    -

    flags must be 0 for now.

    -
    Note
    The initiator initiator should be of type HWLOC_LOCATION_TYPE_CPUSET when refering to accesses performed by CPU cores. HWLOC_LOCATION_TYPE_OBJECT is currently unused internally by hwloc, but users may for instance use it to provide custom information about host memory accesses performed by GPUs.
    - -
    -
    -
    - - - - - - - -
    -
    -Enumerations | -Functions
    -
    -
    Managing memory attributes
    -
    -
    - - - - -

    -Enumerations

    enum  hwloc_memattr_flag_e { HWLOC_MEMATTR_FLAG_HIGHER_FIRST = (1UL<<0) -, HWLOC_MEMATTR_FLAG_LOWER_FIRST = (1UL<<1) -, HWLOC_MEMATTR_FLAG_NEED_INITIATOR = (1UL<<2) - }
     
    - - - - - - - - - - - - - -

    -Functions

    int hwloc_memattr_get_name (hwloc_topology_t topology, hwloc_memattr_id_t attribute, const char **name)
     
    int hwloc_memattr_get_flags (hwloc_topology_t topology, hwloc_memattr_id_t attribute, unsigned long *flags)
     
    int hwloc_memattr_register (hwloc_topology_t topology, const char *name, unsigned long flags, hwloc_memattr_id_t *id)
     
    int hwloc_memattr_set_value (hwloc_topology_t topology, hwloc_memattr_id_t attribute, hwloc_obj_t target_node, struct hwloc_location *initiator, unsigned long flags, hwloc_uint64_t value)
     
    int hwloc_memattr_get_targets (hwloc_topology_t topology, hwloc_memattr_id_t attribute, struct hwloc_location *initiator, unsigned long flags, unsigned *nr, hwloc_obj_t *targets, hwloc_uint64_t *values)
     
    int hwloc_memattr_get_initiators (hwloc_topology_t topology, hwloc_memattr_id_t attribute, hwloc_obj_t target_node, unsigned long flags, unsigned *nr, struct hwloc_location *initiators, hwloc_uint64_t *values)
     
    -

    Detailed Description

    -

    Enumeration Type Documentation

    - -

    ◆ hwloc_memattr_flag_e

    - -
    -
    - - - - -
    enum hwloc_memattr_flag_e
    -
    - -

    Memory attribute flags. Given to hwloc_memattr_register() and returned by hwloc_memattr_get_flags().

    - - - - -
    Enumerator
    HWLOC_MEMATTR_FLAG_HIGHER_FIRST 

    The best nodes for this memory attribute are those with the higher values. For instance Bandwidth.

    -
    HWLOC_MEMATTR_FLAG_LOWER_FIRST 

    The best nodes for this memory attribute are those with the lower values. For instance Latency.

    -
    HWLOC_MEMATTR_FLAG_NEED_INITIATOR 

    The value returned for this memory attribute depends on the given initiator. For instance Bandwidth and Latency, but not Capacity.

    -
    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_memattr_get_flags()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_memattr_get_flags (hwloc_topology_t topology,
    hwloc_memattr_id_t attribute,
    unsigned long * flags 
    )
    -
    - -

    Return the flags of the given attribute.

    -

    Flags are a OR'ed set of hwloc_memattr_flag_e.

    - -
    -
    - -

    ◆ hwloc_memattr_get_initiators()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_memattr_get_initiators (hwloc_topology_t topology,
    hwloc_memattr_id_t attribute,
    hwloc_obj_t target_node,
    unsigned long flags,
    unsigned * nr,
    struct hwloc_location * initiators,
    hwloc_uint64_t * values 
    )
    -
    - -

    Return the initiators that have values for a given attribute for a specific target NUMA node.

    -

    Return initiators for the given attribute and target node in the initiators array. If values is not NULL, the corresponding attribute values are stored in the array it points to.

    -

    On input, nr points to the number of initiators that may be stored in the array initiators (and values). On output, nr points to the number of initiators (and values) that were actually found, even if some of them couldn't be stored in the array. Initiators that couldn't be stored are ignored, but the function still returns success (0). The caller may find out by comparing the value pointed by nr before and after the function call.

    -

    The returned initiators should not be modified or freed, they belong to the topology.

    -

    flags must be 0 for now.

    -

    If the attribute does not relate to a specific initiator (it does not have the flag HWLOC_MEMATTR_FLAG_NEED_INITIATOR), no initiator is returned.

    -
    Note
    This function is meant for tools and debugging (listing internal information) rather than for application queries. Applications should rather select useful NUMA nodes with hwloc_get_local_numanode_objs() and then look at their attribute values for some relevant initiators.
    - -
    -
    - -

    ◆ hwloc_memattr_get_name()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_memattr_get_name (hwloc_topology_t topology,
    hwloc_memattr_id_t attribute,
    const char ** name 
    )
    -
    - -

    Return the name of a memory attribute.

    - -
    -
    - -

    ◆ hwloc_memattr_get_targets()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_memattr_get_targets (hwloc_topology_t topology,
    hwloc_memattr_id_t attribute,
    struct hwloc_location * initiator,
    unsigned long flags,
    unsigned * nr,
    hwloc_obj_t * targets,
    hwloc_uint64_t * values 
    )
    -
    - -

    Return the target NUMA nodes that have some values for a given attribute.

    -

    Return targets for the given attribute in the targets array (for the given initiator if any). If values is not NULL, the corresponding attribute values are stored in the array it points to.

    -

    On input, nr points to the number of targets that may be stored in the array targets (and values). On output, nr points to the number of targets (and values) that were actually found, even if some of them couldn't be stored in the array. Targets that couldn't be stored are ignored, but the function still returns success (0). The caller may find out by comparing the value pointed by nr before and after the function call.

    -

    The returned targets should not be modified or freed, they belong to the topology.

    -

    Argument initiator is ignored if the attribute does not relate to a specific initiator (it does not have the flag HWLOC_MEMATTR_FLAG_NEED_INITIATOR). Otherwise initiator may be non NULL to report only targets that have a value for that initiator.

    -

    flags must be 0 for now.

    -
    Note
    This function is meant for tools and debugging (listing internal information) rather than for application queries. Applications should rather select useful NUMA nodes with hwloc_get_local_numanode_objs() and then look at their attribute values.
    -
    -The initiator initiator should be of type HWLOC_LOCATION_TYPE_CPUSET when referring to accesses performed by CPU cores. HWLOC_LOCATION_TYPE_OBJECT is currently unused internally by hwloc, but users may for instance use it to provide custom information about host memory accesses performed by GPUs.
    - -
    -
    - -

    ◆ hwloc_memattr_register()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_memattr_register (hwloc_topology_t topology,
    const char * name,
    unsigned long flags,
    hwloc_memattr_id_t * id 
    )
    -
    - -

    Register a new memory attribute.

    -

    Add a specific memory attribute that is not defined in hwloc_memattr_id_e. Flags are a OR'ed set of hwloc_memattr_flag_e. It must contain at least one of HWLOC_MEMATTR_FLAG_HIGHER_FIRST or HWLOC_MEMATTR_FLAG_LOWER_FIRST.

    - -
    -
    - -

    ◆ hwloc_memattr_set_value()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_memattr_set_value (hwloc_topology_t topology,
    hwloc_memattr_id_t attribute,
    hwloc_obj_t target_node,
    struct hwloc_location * initiator,
    unsigned long flags,
    hwloc_uint64_t value 
    )
    -
    - -

    Set an attribute value for a specific target NUMA node.

    -

    If the attribute does not relate to a specific initiator (it does not have the flag HWLOC_MEMATTR_FLAG_NEED_INITIATOR), location initiator is ignored and may be NULL.

    -

    The initiator will be copied into the topology, the caller should free anything allocated to store the initiator, for instance the cpuset.

    -

    flags must be 0 for now.

    -
    Note
    The initiator initiator should be of type HWLOC_LOCATION_TYPE_CPUSET when referring to accesses performed by CPU cores. HWLOC_LOCATION_TYPE_OBJECT is currently unused internally by hwloc, but users may for instance use it to provide custom information about host memory accesses performed by GPUs.
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    -
    Kinds of CPU cores
    -
    -
    - - - - - - - - - - -

    -Functions

    int hwloc_cpukinds_get_nr (hwloc_topology_t topology, unsigned long flags)
     
    int hwloc_cpukinds_get_by_cpuset (hwloc_topology_t topology, hwloc_const_bitmap_t cpuset, unsigned long flags)
     
    int hwloc_cpukinds_get_info (hwloc_topology_t topology, unsigned kind_index, hwloc_bitmap_t cpuset, int *efficiency, unsigned *nr_infos, struct hwloc_info_s **infos, unsigned long flags)
     
    int hwloc_cpukinds_register (hwloc_topology_t topology, hwloc_bitmap_t cpuset, int forced_efficiency, unsigned nr_infos, struct hwloc_info_s *infos, unsigned long flags)
     
    -

    Detailed Description

    -

    Platforms with heterogeneous CPUs may have some cores with different features or frequencies. This API exposes identical PUs in sets called CPU kinds. Each PU of the topology may only be in a single kind.

    -

    The number of kinds may be obtained with hwloc_cpukinds_get_nr(). If the platform is homogeneous, there may be a single kind with all PUs. If the platform or operating system does not expose any information about CPU cores, there may be no kind at all.

    -

    The index of the kind that describes a given CPU set (if any, and not partially) may be obtained with hwloc_cpukinds_get_by_cpuset().

    -

    From the index of a kind, it is possible to retrieve information with hwloc_cpukinds_get_info(): an abstracted efficiency value, and an array of info attributes (for instance the "CoreType" and "FrequencyMaxMHz", see CPU Kinds).

    -

    A higher efficiency value means greater intrinsic performance (and possibly less performance/power efficiency). Kinds with lower efficiency values are ranked first: Passing 0 as kind_index to hwloc_cpukinds_get_info() will return information about the CPU kind with lower performance but higher energy-efficiency. Higher kind_index values would rather return information about power-hungry high-performance cores.

    -

    When available, efficiency values are gathered from the operating system. If so, cpukind_efficiency is set in the struct hwloc_topology_discovery_support array. This is currently available on Windows 10, Mac OS X (Darwin), and on some Linux platforms where core "capacity" is exposed in sysfs.

    -

    If the operating system does not expose core efficiencies natively, hwloc tries to compute efficiencies by comparing CPU kinds using frequencies (on ARM), or core types and frequencies (on other architectures). The environment variable HWLOC_CPUKINDS_RANKING may be used to change this heuristics, see Environment Variables.

    -

    If hwloc fails to rank any kind, for instance because the operating system does not expose efficiencies and core frequencies, all kinds will have an unknown efficiency (-1), and they are not indexed/ordered in any specific way.

    -

    Function Documentation

    - -

    ◆ hwloc_cpukinds_get_by_cpuset()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_cpukinds_get_by_cpuset (hwloc_topology_t topology,
    hwloc_const_bitmap_t cpuset,
    unsigned long flags 
    )
    -
    - -

    Get the index of the CPU kind that contains CPUs listed in cpuset.

    -

    flags must be 0 for now.

    -
    Returns
    The index of the CPU kind (positive integer or 0) on success.
    -
    --1 with errno set to EXDEV if cpuset is only partially included in the some kind.
    -
    --1 with errno set to ENOENT if cpuset is not included in any kind, even partially.
    -
    --1 with errno set to EINVAL if parameters are invalid.
    - -
    -
    - -

    ◆ hwloc_cpukinds_get_info()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_cpukinds_get_info (hwloc_topology_t topology,
    unsigned kind_index,
    hwloc_bitmap_t cpuset,
    int * efficiency,
    unsigned * nr_infos,
    struct hwloc_info_s ** infos,
    unsigned long flags 
    )
    -
    - -

    Get the CPU set and infos about a CPU kind in the topology.

    -

    kind_index identifies one kind of CPU between 0 and the number of kinds returned by hwloc_cpukinds_get_nr() minus 1.

    -

    If not NULL, the bitmap cpuset will be filled with the set of PUs of this kind.

    -

    The integer pointed by efficiency, if not NULL will, be filled with the ranking of this kind of CPU in term of efficiency (see above). It ranges from 0 to the number of kinds (as reported by hwloc_cpukinds_get_nr()) minus 1.

    -

    Kinds with lower efficiency are reported first.

    -

    If there is a single kind in the topology, its efficiency 0. If the efficiency of some kinds of cores is unknown, the efficiency of all kinds is set to -1, and kinds are reported in no specific order.

    -

    The array of info attributes (for instance the "CoreType", "FrequencyMaxMHz" or "FrequencyBaseMHz", see CPU Kinds) and its length are returned in infos or nr_infos. The array belongs to the topology, it should not be freed or modified.

    -

    If nr_infos or infos is NULL, no info is returned.

    -

    flags must be 0 for now.

    -
    Returns
    0 on success.
    -
    --1 with errno set to ENOENT if kind_index does not match any CPU kind.
    -
    --1 with errno set to EINVAL if parameters are invalid.
    - -
    -
    - -

    ◆ hwloc_cpukinds_get_nr()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_cpukinds_get_nr (hwloc_topology_t topology,
    unsigned long flags 
    )
    -
    - -

    Get the number of different kinds of CPU cores in the topology.

    -

    flags must be 0 for now.

    -
    Returns
    The number of CPU kinds (positive integer) on success.
    -
    -0 if no information about kinds was found.
    -
    --1 with errno set to EINVAL if flags is invalid.
    - -
    -
    - -

    ◆ hwloc_cpukinds_register()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_cpukinds_register (hwloc_topology_t topology,
    hwloc_bitmap_t cpuset,
    int forced_efficiency,
    unsigned nr_infos,
    struct hwloc_info_s * infos,
    unsigned long flags 
    )
    -
    - -

    Register a kind of CPU in the topology.

    -

    Mark the PUs listed in cpuset as being of the same kind with respect to the given attributes.

    -

    forced_efficiency should be -1 if unknown. Otherwise it is an abstracted efficiency value to enforce the ranking of all kinds if all of them have valid (and different) efficiencies.

    -

    The array infos of size nr_infos may be used to provide info names and values describing this kind of PUs.

    -

    flags must be 0 for now.

    -

    Parameters cpuset and infos will be duplicated internally, the caller is responsible for freeing them.

    -

    If cpuset overlaps with some existing kinds, those might get modified or split. For instance if existing kind A contains PUs 0 and 1, and one registers another kind for PU 1 and 2, there will be 3 resulting kinds: existing kind A is restricted to only PU 0; new kind B contains only PU 1 and combines information from A and from the newly-registered kind; new kind C contains only PU 2 and only gets information from the newly-registered kind.

    -
    Note
    The efficiency forced_efficiency provided to this function may be different from the one reported later by hwloc_cpukinds_get_info() because hwloc will scale efficiency values down to between 0 and the number of kinds minus 1.
    -
    Returns
    0 on success.
    -
    --1 with errno set to EINVAL if some parameters are invalid, for instance if cpuset is NULL or empty.
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    -
    Linux-specific helpers
    -
    -
    - - - - - - - - - - -

    -Functions

    int hwloc_linux_set_tid_cpubind (hwloc_topology_t topology, pid_t tid, hwloc_const_cpuset_t set)
     
    int hwloc_linux_get_tid_cpubind (hwloc_topology_t topology, pid_t tid, hwloc_cpuset_t set)
     
    int hwloc_linux_get_tid_last_cpu_location (hwloc_topology_t topology, pid_t tid, hwloc_bitmap_t set)
     
    int hwloc_linux_read_path_as_cpumask (const char *path, hwloc_bitmap_t set)
     
    -

    Detailed Description

    -

    This includes helpers for manipulating Linux kernel cpumap files, and hwloc equivalents of the Linux sched_setaffinity and sched_getaffinity system calls.

    -

    Function Documentation

    - -

    ◆ hwloc_linux_get_tid_cpubind()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_linux_get_tid_cpubind (hwloc_topology_t topology,
    pid_t tid,
    hwloc_cpuset_t set 
    )
    -
    - -

    Get the current binding of thread tid.

    -

    The CPU-set set (previously allocated by the caller) is filled with the list of PUs which the thread was last bound to.

    -

    The behavior is exactly the same as the Linux sched_getaffinity system call, but uses a hwloc cpuset.

    -
    Note
    This is equivalent to calling hwloc_get_proc_cpubind() with HWLOC_CPUBIND_THREAD as flags.
    - -
    -
    - -

    ◆ hwloc_linux_get_tid_last_cpu_location()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_linux_get_tid_last_cpu_location (hwloc_topology_t topology,
    pid_t tid,
    hwloc_bitmap_t set 
    )
    -
    - -

    Get the last physical CPU where thread tid ran.

    -

    The CPU-set set (previously allocated by the caller) is filled with the PU which the thread last ran on.

    -
    Note
    This is equivalent to calling hwloc_get_proc_last_cpu_location() with HWLOC_CPUBIND_THREAD as flags.
    - -
    -
    - -

    ◆ hwloc_linux_read_path_as_cpumask()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_linux_read_path_as_cpumask (const char * path,
    hwloc_bitmap_t set 
    )
    -
    - -

    Convert a linux kernel cpumask file path into a hwloc bitmap set.

    -

    Might be used when reading CPU set from sysfs attributes such as topology and caches for processors, or local_cpus for devices.

    -
    Note
    This function ignores the HWLOC_FSROOT environment variable.
    - -
    -
    - -

    ◆ hwloc_linux_set_tid_cpubind()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_linux_set_tid_cpubind (hwloc_topology_t topology,
    pid_t tid,
    hwloc_const_cpuset_t set 
    )
    -
    - -

    Bind a thread tid on cpus given in cpuset set.

    -

    The behavior is exactly the same as the Linux sched_setaffinity system call, but uses a hwloc cpuset.

    -
    Note
    This is equivalent to calling hwloc_set_proc_cpubind() with HWLOC_CPUBIND_THREAD as flags.
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    -
    Interoperability with Linux libnuma unsigned long masks
    -
    -
    - - - - - - - - - - -

    -Functions

    static int hwloc_cpuset_to_linux_libnuma_ulongs (hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, unsigned long *mask, unsigned long *maxnode)
     
    static int hwloc_nodeset_to_linux_libnuma_ulongs (hwloc_topology_t topology, hwloc_const_nodeset_t nodeset, unsigned long *mask, unsigned long *maxnode)
     
    static int hwloc_cpuset_from_linux_libnuma_ulongs (hwloc_topology_t topology, hwloc_cpuset_t cpuset, const unsigned long *mask, unsigned long maxnode)
     
    static int hwloc_nodeset_from_linux_libnuma_ulongs (hwloc_topology_t topology, hwloc_nodeset_t nodeset, const unsigned long *mask, unsigned long maxnode)
     
    -

    Detailed Description

    -

    This interface helps converting between Linux libnuma unsigned long masks and hwloc cpusets and nodesets.

    -
    Note
    Topology topology must match the current machine.
    -
    -The behavior of libnuma is undefined if the kernel is not NUMA-aware. (when CONFIG_NUMA is not set in the kernel configuration). This helper and libnuma may thus not be strictly compatible in this case, which may be detected by checking whether numa_available() returns -1.
    -

    Function Documentation

    - -

    ◆ hwloc_cpuset_from_linux_libnuma_ulongs()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_cpuset_from_linux_libnuma_ulongs (hwloc_topology_t topology,
    hwloc_cpuset_t cpuset,
    const unsigned long * mask,
    unsigned long maxnode 
    )
    -     		-inlinestatic
    -
    - -

    Convert the array of unsigned long mask into hwloc CPU set.

    -

    mask is a array of unsigned long that will be read. maxnode contains the maximal node number that may be read in mask.

    -

    This function may be used after calling get_mempolicy or any other function that takes an array of unsigned long as output parameter (and possibly a maximal node number as input parameter).

    - -
    -
    - -

    ◆ hwloc_cpuset_to_linux_libnuma_ulongs()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_cpuset_to_linux_libnuma_ulongs (hwloc_topology_t topology,
    hwloc_const_cpuset_t cpuset,
    unsigned long * mask,
    unsigned long * maxnode 
    )
    -     		-inlinestatic
    -
    - -

    Convert hwloc CPU set cpuset into the array of unsigned long mask.

    -

    mask is the array of unsigned long that will be filled. maxnode contains the maximal node number that may be stored in mask. maxnode will be set to the maximal node number that was found, plus one.

    -

    This function may be used before calling set_mempolicy, mbind, migrate_pages or any other function that takes an array of unsigned long and a maximal node number as input parameter.

    - -
    -
    - -

    ◆ hwloc_nodeset_from_linux_libnuma_ulongs()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_nodeset_from_linux_libnuma_ulongs (hwloc_topology_t topology,
    hwloc_nodeset_t nodeset,
    const unsigned long * mask,
    unsigned long maxnode 
    )
    -     		-inlinestatic
    -
    - -

    Convert the array of unsigned long mask into hwloc NUMA node set.

    -

    mask is a array of unsigned long that will be read. maxnode contains the maximal node number that may be read in mask.

    -

    This function may be used after calling get_mempolicy or any other function that takes an array of unsigned long as output parameter (and possibly a maximal node number as input parameter).

    - -
    -
    - -

    ◆ hwloc_nodeset_to_linux_libnuma_ulongs()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_nodeset_to_linux_libnuma_ulongs (hwloc_topology_t topology,
    hwloc_const_nodeset_t nodeset,
    unsigned long * mask,
    unsigned long * maxnode 
    )
    -     		-inlinestatic
    -
    - -

    Convert hwloc NUMA node set nodeset into the array of unsigned long mask.

    -

    mask is the array of unsigned long that will be filled. maxnode contains the maximal node number that may be stored in mask. maxnode will be set to the maximal node number that was found, plus one.

    -

    This function may be used before calling set_mempolicy, mbind, migrate_pages or any other function that takes an array of unsigned long and a maximal node number as input parameter.

    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    -
    Interoperability with Linux libnuma bitmask
    -
    -
    - - - - - - - - - - -

    -Functions

    static struct bitmask * hwloc_cpuset_to_linux_libnuma_bitmask (hwloc_topology_t topology, hwloc_const_cpuset_t cpuset)
     
    static struct bitmask * hwloc_nodeset_to_linux_libnuma_bitmask (hwloc_topology_t topology, hwloc_const_nodeset_t nodeset)
     
    static int hwloc_cpuset_from_linux_libnuma_bitmask (hwloc_topology_t topology, hwloc_cpuset_t cpuset, const struct bitmask *bitmask)
     
    static int hwloc_nodeset_from_linux_libnuma_bitmask (hwloc_topology_t topology, hwloc_nodeset_t nodeset, const struct bitmask *bitmask)
     
    -

    Detailed Description

    -

    This interface helps converting between Linux libnuma bitmasks and hwloc cpusets and nodesets.

    -
    Note
    Topology topology must match the current machine.
    -
    -The behavior of libnuma is undefined if the kernel is not NUMA-aware. (when CONFIG_NUMA is not set in the kernel configuration). This helper and libnuma may thus not be strictly compatible in this case, which may be detected by checking whether numa_available() returns -1.
    -

    Function Documentation

    - -

    ◆ hwloc_cpuset_from_linux_libnuma_bitmask()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_cpuset_from_linux_libnuma_bitmask (hwloc_topology_t topology,
    hwloc_cpuset_t cpuset,
    const struct bitmask * bitmask 
    )
    -     		-inlinestatic
    -
    - -

    Convert libnuma bitmask bitmask into hwloc CPU set cpuset.

    -

    This function may be used after calling many numa_ functions that use a struct bitmask as an output parameter.

    - -
    -
    - -

    ◆ hwloc_cpuset_to_linux_libnuma_bitmask()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static struct bitmask * hwloc_cpuset_to_linux_libnuma_bitmask (hwloc_topology_t topology,
    hwloc_const_cpuset_t cpuset 
    )
    -     		-inlinestatic
    -
    - -

    Convert hwloc CPU set cpuset into the returned libnuma bitmask.

    -

    The returned bitmask should later be freed with numa_bitmask_free.

    -

    This function may be used before calling many numa_ functions that use a struct bitmask as an input parameter.

    -
    Returns
    newly allocated struct bitmask.
    - -
    -
    - -

    ◆ hwloc_nodeset_from_linux_libnuma_bitmask()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_nodeset_from_linux_libnuma_bitmask (hwloc_topology_t topology,
    hwloc_nodeset_t nodeset,
    const struct bitmask * bitmask 
    )
    -     		-inlinestatic
    -
    - -

    Convert libnuma bitmask bitmask into hwloc NUMA node set nodeset.

    -

    This function may be used after calling many numa_ functions that use a struct bitmask as an output parameter.

    - -
    -
    - -

    ◆ hwloc_nodeset_to_linux_libnuma_bitmask()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static struct bitmask * hwloc_nodeset_to_linux_libnuma_bitmask (hwloc_topology_t topology,
    hwloc_const_nodeset_t nodeset 
    )
    -     		-inlinestatic
    -
    - -

    Convert hwloc NUMA node set nodeset into the returned libnuma bitmask.

    -

    The returned bitmask should later be freed with numa_bitmask_free.

    -

    This function may be used before calling many numa_ functions that use a struct bitmask as an input parameter.

    -
    Returns
    newly allocated struct bitmask.
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    -
    Windows-specific helpers
    -
    -
    - - - - - - -

    -Functions

    int hwloc_windows_get_nr_processor_groups (hwloc_topology_t topology, unsigned long flags)
     
    int hwloc_windows_get_processor_group_cpuset (hwloc_topology_t topology, unsigned pg_index, hwloc_cpuset_t cpuset, unsigned long flags)
     
    -

    Detailed Description

    -

    These functions query Windows processor groups. These groups partition the operating system into virtual sets of up to 64 neighbor PUs. Threads and processes may only be bound inside a single group. Although Windows processor groups may be exposed in the hwloc hierarchy as hwloc Groups, they are also often merged into existing hwloc objects such as NUMA nodes or Packages. This API provides explicit information about Windows processor groups so that applications know whether binding to a large set of PUs may fail because it spans over multiple Windows processor groups.

    -

    Function Documentation

    - -

    ◆ hwloc_windows_get_nr_processor_groups()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_windows_get_nr_processor_groups (hwloc_topology_t topology,
    unsigned long flags 
    )
    -
    - -

    Get the number of Windows processor groups.

    -

    flags must be 0 for now.

    -
    Returns
    at least 1 on success.
    -
    --1 on error, for instance if the topology does not match the current system (e.g. loaded from another machine through XML).
    - -
    -
    - -

    ◆ hwloc_windows_get_processor_group_cpuset()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_windows_get_processor_group_cpuset (hwloc_topology_t topology,
    unsigned pg_index,
    hwloc_cpuset_t cpuset,
    unsigned long flags 
    )
    -
    - -

    Get the CPU-set of a Windows processor group.

    -

    Get the set of PU included in the processor group specified by pg_index. pg_index must be between 0 and the value returned by hwloc_windows_get_nr_processor_groups() minus 1.

    -

    flags must be 0 for now.

    -
    Returns
    0 on success.
    -
    --1 on error, for instance if pg_index is invalid, or if the topology does not match the current system (e.g. loaded from another machine through XML).
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    -
    Interoperability with glibc sched affinity
    -
    -
    - - - - - - -

    -Functions

    static int hwloc_cpuset_to_glibc_sched_affinity (hwloc_topology_t topology, hwloc_const_cpuset_t hwlocset, cpu_set_t *schedset, size_t schedsetsize)
     
    static int hwloc_cpuset_from_glibc_sched_affinity (hwloc_topology_t topology, hwloc_cpuset_t hwlocset, const cpu_set_t *schedset, size_t schedsetsize)
     
    -

    Detailed Description

    -

    This interface offers ways to convert between hwloc cpusets and glibc cpusets such as those manipulated by sched_getaffinity() or pthread_attr_setaffinity_np().

    -
    Note
    Topology topology must match the current machine.
    -

    Function Documentation

    - -

    ◆ hwloc_cpuset_from_glibc_sched_affinity()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_cpuset_from_glibc_sched_affinity (hwloc_topology_t topology,
    hwloc_cpuset_t hwlocset,
    const cpu_set_t * schedset,
    size_t schedsetsize 
    )
    -     		-inlinestatic
    -
    - -

    Convert glibc sched affinity CPU set schedset into hwloc CPU set.

    -

    This function may be used before calling sched_setaffinity or any other function that takes a cpu_set_t as input parameter.

    -

    schedsetsize should be sizeof(cpu_set_t) unless schedset was dynamically allocated with CPU_ALLOC

    - -
    -
    - -

    ◆ hwloc_cpuset_to_glibc_sched_affinity()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_cpuset_to_glibc_sched_affinity (hwloc_topology_t topology,
    hwloc_const_cpuset_t hwlocset,
    cpu_set_t * schedset,
    size_t schedsetsize 
    )
    -     		-inlinestatic
    -
    - -

    Convert hwloc CPU set toposet into glibc sched affinity CPU set schedset.

    -

    This function may be used before calling sched_setaffinity or any other function that takes a cpu_set_t as input parameter.

    -

    schedsetsize should be sizeof(cpu_set_t) unless schedset was dynamically allocated with CPU_ALLOC

    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    -
    Interoperability with OpenCL
    -
    -
    - - - - - - - - - - -

    -Functions

    static int hwloc_opencl_get_device_pci_busid (cl_device_id device, unsigned *domain, unsigned *bus, unsigned *dev, unsigned *func)
     
    static int hwloc_opencl_get_device_cpuset (hwloc_topology_t topology, cl_device_id device, hwloc_cpuset_t set)
     
    static hwloc_obj_t hwloc_opencl_get_device_osdev_by_index (hwloc_topology_t topology, unsigned platform_index, unsigned device_index)
     
    static hwloc_obj_t hwloc_opencl_get_device_osdev (hwloc_topology_t topology, cl_device_id device)
     
    -

    Detailed Description

    -

    This interface offers ways to retrieve topology information about OpenCL devices.

    -

    Only AMD and NVIDIA OpenCL implementations currently offer useful locality information about their devices.

    -

    Function Documentation

    - -

    ◆ hwloc_opencl_get_device_cpuset()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_opencl_get_device_cpuset (hwloc_topology_t topology,
    cl_device_id device,
    hwloc_cpuset_t set 
    )
    -     		-inlinestatic
    -
    - -

    Get the CPU set of processors that are physically close to OpenCL device device.

    -

    Store in set the CPU-set describing the locality of the OpenCL device device.

    -

    Topology topology and device device must match the local machine. I/O devices detection and the OpenCL component are not needed in the topology.

    -

    The function only returns the locality of the device. If more information about the device is needed, OS objects should be used instead, see hwloc_opencl_get_device_osdev() and hwloc_opencl_get_device_osdev_by_index().

    -

    This function is currently only implemented in a meaningful way for Linux with the AMD or NVIDIA OpenCL implementation; other systems will simply get a full cpuset.

    - -
    -
    - -

    ◆ hwloc_opencl_get_device_osdev()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_opencl_get_device_osdev (hwloc_topology_t topology,
    cl_device_id device 
    )
    -     		-inlinestatic
    -
    - -

    Get the hwloc OS device object corresponding to OpenCL device deviceX.

    -
    Returns
    The hwloc OS device object corresponding to the given OpenCL device device.
    -
    -NULL if none could be found, for instance if required OpenCL attributes are not available.
    -

    This function currently only works on AMD and NVIDIA OpenCL devices that support relevant OpenCL extensions. hwloc_opencl_get_device_osdev_by_index() should be preferred whenever possible, i.e. when platform and device index are known.

    -

    Topology topology and device device must match the local machine. I/O devices detection and the OpenCL component must be enabled in the topology. If not, the locality of the object may still be found using hwloc_opencl_get_device_cpuset().

    -
    Note
    This function cannot work if PCI devices are filtered out.
    -
    -The corresponding hwloc PCI device may be found by looking at the result parent pointer (unless PCI devices are filtered out).
    - -
    -
    - -

    ◆ hwloc_opencl_get_device_osdev_by_index()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_opencl_get_device_osdev_by_index (hwloc_topology_t topology,
    unsigned platform_index,
    unsigned device_index 
    )
    -     		-inlinestatic
    -
    - -

    Get the hwloc OS device object corresponding to the OpenCL device for the given indexes.

    -
    Returns
    The hwloc OS device object describing the OpenCL device whose platform index is platform_index, and whose device index within this platform if device_index.
    -
    -NULL if there is none.
    -

    The topology topology does not necessarily have to match the current machine. For instance the topology may be an XML import of a remote host. I/O devices detection and the OpenCL component must be enabled in the topology.

    -
    Note
    The corresponding PCI device object can be obtained by looking at the OS device parent object (unless PCI devices are filtered out).
    - -
    -
    - -

    ◆ hwloc_opencl_get_device_pci_busid()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_opencl_get_device_pci_busid (cl_device_id device,
    unsigned * domain,
    unsigned * bus,
    unsigned * dev,
    unsigned * func 
    )
    -     		-inlinestatic
    -
    - -

    Return the domain, bus and device IDs of the OpenCL device device.

    -

    Device device must match the local machine.

    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    -
    Interoperability with the CUDA Driver API
    -
    -
    - - - - - - - - - - - - -

    -Functions

    static int hwloc_cuda_get_device_pci_ids (hwloc_topology_t topology, CUdevice cudevice, int *domain, int *bus, int *dev)
     
    static int hwloc_cuda_get_device_cpuset (hwloc_topology_t topology, CUdevice cudevice, hwloc_cpuset_t set)
     
    static hwloc_obj_t hwloc_cuda_get_device_pcidev (hwloc_topology_t topology, CUdevice cudevice)
     
    static hwloc_obj_t hwloc_cuda_get_device_osdev (hwloc_topology_t topology, CUdevice cudevice)
     
    static hwloc_obj_t hwloc_cuda_get_device_osdev_by_index (hwloc_topology_t topology, unsigned idx)
     
    -

    Detailed Description

    -

    This interface offers ways to retrieve topology information about CUDA devices when using the CUDA Driver API.

    -

    Function Documentation

    - -

    ◆ hwloc_cuda_get_device_cpuset()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_cuda_get_device_cpuset (hwloc_topology_t topology,
    CUdevice cudevice,
    hwloc_cpuset_t set 
    )
    -     		-inlinestatic
    -
    - -

    Get the CPU set of processors that are physically close to device cudevice.

    -

    Store in set the CPU-set describing the locality of the CUDA device cudevice.

    -

    Topology topology and device cudevice must match the local machine. I/O devices detection and the CUDA component are not needed in the topology.

    -

    The function only returns the locality of the device. If more information about the device is needed, OS objects should be used instead, see hwloc_cuda_get_device_osdev() and hwloc_cuda_get_device_osdev_by_index().

    -

    This function is currently only implemented in a meaningful way for Linux; other systems will simply get a full cpuset.

    - -
    -
    - -

    ◆ hwloc_cuda_get_device_osdev()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_cuda_get_device_osdev (hwloc_topology_t topology,
    CUdevice cudevice 
    )
    -     		-inlinestatic
    -
    - -

    Get the hwloc OS device object corresponding to CUDA device cudevice.

    -
    Returns
    The hwloc OS device object that describes the given CUDA device cudevice.
    -
    -NULL if none could be found.
    -

    Topology topology and device cudevice must match the local machine. I/O devices detection and the CUDA component must be enabled in the topology. If not, the locality of the object may still be found using hwloc_cuda_get_device_cpuset().

    -
    Note
    This function cannot work if PCI devices are filtered out.
    -
    -The corresponding hwloc PCI device may be found by looking at the result parent pointer (unless PCI devices are filtered out).
    - -
    -
    - -

    ◆ hwloc_cuda_get_device_osdev_by_index()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_cuda_get_device_osdev_by_index (hwloc_topology_t topology,
    unsigned idx 
    )
    -     		-inlinestatic
    -
    - -

    Get the hwloc OS device object corresponding to the CUDA device whose index is idx.

    -
    Returns
    The hwloc OS device object describing the CUDA device whose index is idx.
    -
    -NULL if none could be found.
    -

    The topology topology does not necessarily have to match the current machine. For instance the topology may be an XML import of a remote host. I/O devices detection and the CUDA component must be enabled in the topology.

    -
    Note
    The corresponding PCI device object can be obtained by looking at the OS device parent object (unless PCI devices are filtered out).
    -
    -This function is identical to hwloc_cudart_get_device_osdev_by_index().
    - -
    -
    - -

    ◆ hwloc_cuda_get_device_pci_ids()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_cuda_get_device_pci_ids (hwloc_topology_t topology,
    CUdevice cudevice,
    int * domain,
    int * bus,
    int * dev 
    )
    -     		-inlinestatic
    -
    - -

    Return the domain, bus and device IDs of the CUDA device cudevice.

    -

    Device cudevice must match the local machine.

    - -
    -
    - -

    ◆ hwloc_cuda_get_device_pcidev()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_cuda_get_device_pcidev (hwloc_topology_t topology,
    CUdevice cudevice 
    )
    -     		-inlinestatic
    -
    - -

    Get the hwloc PCI device object corresponding to the CUDA device cudevice.

    -
    Returns
    The hwloc PCI device object describing the CUDA device cudevice.
    -
    -NULL if none could be found.
    -

    Topology topology and device cudevice must match the local machine. I/O devices detection must be enabled in topology topology. The CUDA component is not needed in the topology.

    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    -
    Interoperability with the CUDA Runtime API
    -
    -
    - - - - - - - - - - -

    -Functions

    static int hwloc_cudart_get_device_pci_ids (hwloc_topology_t topology, int idx, int *domain, int *bus, int *dev)
     
    static int hwloc_cudart_get_device_cpuset (hwloc_topology_t topology, int idx, hwloc_cpuset_t set)
     
    static hwloc_obj_t hwloc_cudart_get_device_pcidev (hwloc_topology_t topology, int idx)
     
    static hwloc_obj_t hwloc_cudart_get_device_osdev_by_index (hwloc_topology_t topology, unsigned idx)
     
    -

    Detailed Description

    -

    This interface offers ways to retrieve topology information about CUDA devices when using the CUDA Runtime API.

    -

    Function Documentation

    - -

    ◆ hwloc_cudart_get_device_cpuset()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_cudart_get_device_cpuset (hwloc_topology_t topology,
    int idx,
    hwloc_cpuset_t set 
    )
    -     		-inlinestatic
    -
    - -

    Get the CPU set of processors that are physically close to device idx.

    -

    Store in set the CPU-set describing the locality of the CUDA device whose index is idx.

    -

    Topology topology and device idx must match the local machine. I/O devices detection and the CUDA component are not needed in the topology.

    -

    The function only returns the locality of the device. If more information about the device is needed, OS objects should be used instead, see hwloc_cudart_get_device_osdev_by_index().

    -

    This function is currently only implemented in a meaningful way for Linux; other systems will simply get a full cpuset.

    - -
    -
    - -

    ◆ hwloc_cudart_get_device_osdev_by_index()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_cudart_get_device_osdev_by_index (hwloc_topology_t topology,
    unsigned idx 
    )
    -     		-inlinestatic
    -
    - -

    Get the hwloc OS device object corresponding to the CUDA device whose index is idx.

    -
    Returns
    The hwloc OS device object describing the CUDA device whose index is idx.
    -
    -NULL if none could be found.
    -

    The topology topology does not necessarily have to match the current machine. For instance the topology may be an XML import of a remote host. I/O devices detection and the CUDA component must be enabled in the topology. If not, the locality of the object may still be found using hwloc_cudart_get_device_cpuset().

    -
    Note
    The corresponding PCI device object can be obtained by looking at the OS device parent object (unless PCI devices are filtered out).
    -
    -This function is identical to hwloc_cuda_get_device_osdev_by_index().
    - -
    -
    - -

    ◆ hwloc_cudart_get_device_pci_ids()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_cudart_get_device_pci_ids (hwloc_topology_t topology,
    int idx,
    int * domain,
    int * bus,
    int * dev 
    )
    -     		-inlinestatic
    -
    - -

    Return the domain, bus and device IDs of the CUDA device whose index is idx.

    -

    Device index idx must match the local machine.

    - -
    -
    - -

    ◆ hwloc_cudart_get_device_pcidev()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_cudart_get_device_pcidev (hwloc_topology_t topology,
    int idx 
    )
    -     		-inlinestatic
    -
    - -

    Get the hwloc PCI device object corresponding to the CUDA device whose index is idx.

    -
    Returns
    The hwloc PCI device object describing the CUDA device whose index is idx.
    -
    -NULL if none could be found.
    -

    Topology topology and device idx must match the local machine. I/O devices detection must be enabled in topology topology. The CUDA component is not needed in the topology.

    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    -
    Interoperability with the NVIDIA Management Library
    -
    -
    - - - - - - - - -

    -Functions

    static int hwloc_nvml_get_device_cpuset (hwloc_topology_t topology, nvmlDevice_t device, hwloc_cpuset_t set)
     
    static hwloc_obj_t hwloc_nvml_get_device_osdev_by_index (hwloc_topology_t topology, unsigned idx)
     
    static hwloc_obj_t hwloc_nvml_get_device_osdev (hwloc_topology_t topology, nvmlDevice_t device)
     
    -

    Detailed Description

    -

    This interface offers ways to retrieve topology information about devices managed by the NVIDIA Management Library (NVML).

    -

    Function Documentation

    - -

    ◆ hwloc_nvml_get_device_cpuset()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_nvml_get_device_cpuset (hwloc_topology_t topology,
    nvmlDevice_t device,
    hwloc_cpuset_t set 
    )
    -     		-inlinestatic
    -
    - -

    Get the CPU set of processors that are physically close to NVML device device.

    -

    Store in set the CPU-set describing the locality of the NVML device device.

    -

    Topology topology and device device must match the local machine. I/O devices detection and the NVML component are not needed in the topology.

    -

    The function only returns the locality of the device. If more information about the device is needed, OS objects should be used instead, see hwloc_nvml_get_device_osdev() and hwloc_nvml_get_device_osdev_by_index().

    -

    This function is currently only implemented in a meaningful way for Linux; other systems will simply get a full cpuset.

    - -
    -
    - -

    ◆ hwloc_nvml_get_device_osdev()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_nvml_get_device_osdev (hwloc_topology_t topology,
    nvmlDevice_t device 
    )
    -     		-inlinestatic
    -
    - -

    Get the hwloc OS device object corresponding to NVML device device.

    -
    Returns
    The hwloc OS device object that describes the given NVML device device.
    -
    -NULL if none could be found.
    -

    Topology topology and device device must match the local machine. I/O devices detection and the NVML component must be enabled in the topology. If not, the locality of the object may still be found using hwloc_nvml_get_device_cpuset().

    -
    Note
    The corresponding hwloc PCI device may be found by looking at the result parent pointer (unless PCI devices are filtered out).
    - -
    -
    - -

    ◆ hwloc_nvml_get_device_osdev_by_index()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_nvml_get_device_osdev_by_index (hwloc_topology_t topology,
    unsigned idx 
    )
    -     		-inlinestatic
    -
    - -

    Get the hwloc OS device object corresponding to the NVML device whose index is idx.

    -
    Returns
    The hwloc OS device object describing the NVML device whose index is idx.
    -
    -NULL if none could be found.
    -

    The topology topology does not necessarily have to match the current machine. For instance the topology may be an XML import of a remote host. I/O devices detection and the NVML component must be enabled in the topology.

    -
    Note
    The corresponding PCI device object can be obtained by looking at the OS device parent object (unless PCI devices are filtered out).
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    -
    Interoperability with the ROCm SMI Management Library
    -
    -
    - - - - - - - - -

    -Functions

    static int hwloc_rsmi_get_device_cpuset (hwloc_topology_t topology, uint32_t dv_ind, hwloc_cpuset_t set)
     
    static hwloc_obj_t hwloc_rsmi_get_device_osdev_by_index (hwloc_topology_t topology, uint32_t dv_ind)
     
    static hwloc_obj_t hwloc_rsmi_get_device_osdev (hwloc_topology_t topology, uint32_t dv_ind)
     
    -

    Detailed Description

    -

    This interface offers ways to retrieve topology information about devices managed by the ROCm SMI Management Library.

    -

    Function Documentation

    - -

    ◆ hwloc_rsmi_get_device_cpuset()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_rsmi_get_device_cpuset (hwloc_topology_t topology,
    uint32_t dv_ind,
    hwloc_cpuset_t set 
    )
    -     		-inlinestatic
    -
    - -

    Get the CPU set of logical processors that are physically close to AMD GPU device whose index is dv_ind.

    -

    Store in set the CPU-set describing the locality of the AMD GPU device whose index is dv_ind.

    -

    Topology topology and device dv_ind must match the local machine. I/O devices detection and the ROCm SMI component are not needed in the topology.

    -

    The function only returns the locality of the device. If more information about the device is needed, OS objects should be used instead, see hwloc_rsmi_get_device_osdev() and hwloc_rsmi_get_device_osdev_by_index().

    -

    This function is currently only implemented in a meaningful way for Linux; other systems will simply get a full cpuset.

    - -
    -
    - -

    ◆ hwloc_rsmi_get_device_osdev()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_rsmi_get_device_osdev (hwloc_topology_t topology,
    uint32_t dv_ind 
    )
    -     		-inlinestatic
    -
    - -

    Get the hwloc OS device object corresponding to AMD GPU device, whose index is dv_ind.

    -
    Returns
    The hwloc OS device object that describes the given AMD GPU, whose index is dv_ind.
    -
    -NULL if none could be found.
    -

    Topology topology and device dv_ind must match the local machine. I/O devices detection and the ROCm SMI component must be enabled in the topology. If not, the locality of the object may still be found using hwloc_rsmi_get_device_cpuset().

    -
    Note
    The corresponding hwloc PCI device may be found by looking at the result parent pointer (unless PCI devices are filtered out).
    - -
    -
    - -

    ◆ hwloc_rsmi_get_device_osdev_by_index()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_rsmi_get_device_osdev_by_index (hwloc_topology_t topology,
    uint32_t dv_ind 
    )
    -     		-inlinestatic
    -
    - -

    Get the hwloc OS device object corresponding to the AMD GPU device whose index is dv_ind.

    -
    Returns
    The hwloc OS device object describing the AMD GPU device whose index is dv_ind.
    -
    -NULL if none could be found.
    -

    The topology topology does not necessarily have to match the current machine. For instance the topology may be an XML import of a remote host. I/O devices detection and the ROCm SMI component must be enabled in the topology.

    -
    Note
    The corresponding PCI device object can be obtained by looking at the OS device parent object (unless PCI devices are filtered out).
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    -
    Interoperability with the oneAPI Level Zero interface.
    -
    -
    - - - - - - -

    -Functions

    static int hwloc_levelzero_get_device_cpuset (hwloc_topology_t topology, ze_device_handle_t device, hwloc_cpuset_t set)
     
    static hwloc_obj_t hwloc_levelzero_get_device_osdev (hwloc_topology_t topology, ze_device_handle_t device)
     
    -

    Detailed Description

    -

    This interface offers ways to retrieve topology information about devices managed by the Level Zero API.

    -

    Function Documentation

    - -

    ◆ hwloc_levelzero_get_device_cpuset()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_levelzero_get_device_cpuset (hwloc_topology_t topology,
    ze_device_handle_t device,
    hwloc_cpuset_t set 
    )
    -     		-inlinestatic
    -
    - -

    Get the CPU set of logical processors that are physically close to the Level Zero device device.

    -

    Store in set the CPU-set describing the locality of the Level Zero device device.

    -

    Topology topology and device device must match the local machine. The Level Zero must have been initialized with Sysman enabled (ZES_ENABLE_SYSMAN=1 in the environment). I/O devices detection and the Level Zero component are not needed in the topology.

    -

    The function only returns the locality of the device. If more information about the device is needed, OS objects should be used instead, see hwloc_levelzero_get_device_osdev().

    -

    This function is currently only implemented in a meaningful way for Linux; other systems will simply get a full cpuset.

    - -
    -
    - -

    ◆ hwloc_levelzero_get_device_osdev()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_levelzero_get_device_osdev (hwloc_topology_t topology,
    ze_device_handle_t device 
    )
    -     		-inlinestatic
    -
    - -

    Get the hwloc OS device object corresponding to Level Zero device device.

    -
    Returns
    The hwloc OS device object that describes the given Level Zero device device.
    -
    -NULL if none could be found.
    -

    Topology topology and device dv_ind must match the local machine. I/O devices detection and the Level Zero component must be enabled in the topology. If not, the locality of the object may still be found using hwloc_levelzero_get_device_cpuset().

    -
    Note
    The corresponding hwloc PCI device may be found by looking at the result parent pointer (unless PCI devices are filtered out).
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    -
    Interoperability with OpenGL displays
    -
    -
    - - - - - - - - -

    -Functions

    static hwloc_obj_t hwloc_gl_get_display_osdev_by_port_device (hwloc_topology_t topology, unsigned port, unsigned device)
     
    static hwloc_obj_t hwloc_gl_get_display_osdev_by_name (hwloc_topology_t topology, const char *name)
     
    static int hwloc_gl_get_display_by_osdev (hwloc_topology_t topology, hwloc_obj_t osdev, unsigned *port, unsigned *device)
     
    -

    Detailed Description

    -

    This interface offers ways to retrieve topology information about OpenGL displays.

    -

    Only the NVIDIA display locality information is currently available, using the NV-CONTROL X11 extension and the NVCtrl library.

    -

    Function Documentation

    - -

    ◆ hwloc_gl_get_display_by_osdev()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_gl_get_display_by_osdev (hwloc_topology_t topology,
    hwloc_obj_t osdev,
    unsigned * port,
    unsigned * device 
    )
    -     		-inlinestatic
    -
    - -

    Get the OpenGL display port and device corresponding to the given hwloc OS object.

    -

    Retrieves the OpenGL display port (server) in port and device (screen) in screen that correspond to the given hwloc OS device object.

    -
    Returns
    -1 if none could be found.
    -

    The topology topology does not necessarily have to match the current machine. For instance the topology may be an XML import of a remote host. I/O devices detection and the GL component must be enabled in the topology.

    - -
    -
    - -

    ◆ hwloc_gl_get_display_osdev_by_name()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_gl_get_display_osdev_by_name (hwloc_topology_t topology,
    const char * name 
    )
    -     		-inlinestatic
    -
    - -

    Get the hwloc OS device object corresponding to the OpenGL display given by name.

    -
    Returns
    The hwloc OS device object describing the OpenGL display whose name is name, built as ":port.device" such as ":0.0" .
    -
    -NULL if none could be found.
    -

    The topology topology does not necessarily have to match the current machine. For instance the topology may be an XML import of a remote host. I/O devices detection and the GL component must be enabled in the topology.

    -
    Note
    The corresponding PCI device object can be obtained by looking at the OS device parent object (unless PCI devices are filtered out).
    - -
    -
    - -

    ◆ hwloc_gl_get_display_osdev_by_port_device()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_gl_get_display_osdev_by_port_device (hwloc_topology_t topology,
    unsigned port,
    unsigned device 
    )
    -     		-inlinestatic
    -
    - -

    Get the hwloc OS device object corresponding to the OpenGL display given by port and device index.

    -
    Returns
    The hwloc OS device object describing the OpenGL display whose port (server) is port and device (screen) is device.
    -
    -NULL if none could be found.
    -

    The topology topology does not necessarily have to match the current machine. For instance the topology may be an XML import of a remote host. I/O devices detection and the GL component must be enabled in the topology.

    -
    Note
    The corresponding PCI device object can be obtained by looking at the OS device parent object (unless PCI devices are filtered out).
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    -
    Interoperability with OpenFabrics
    -
    -
    - - - - - - - - -

    -Functions

    static int hwloc_ibv_get_device_cpuset (hwloc_topology_t topology, struct ibv_device *ibdev, hwloc_cpuset_t set)
     
    static hwloc_obj_t hwloc_ibv_get_device_osdev_by_name (hwloc_topology_t topology, const char *ibname)
     
    static hwloc_obj_t hwloc_ibv_get_device_osdev (hwloc_topology_t topology, struct ibv_device *ibdev)
     
    -

    Detailed Description

    -

    This interface offers ways to retrieve topology information about OpenFabrics devices (InfiniBand, Omni-Path, usNIC, etc).

    -

    Function Documentation

    - -

    ◆ hwloc_ibv_get_device_cpuset()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_ibv_get_device_cpuset (hwloc_topology_t topology,
    struct ibv_device * ibdev,
    hwloc_cpuset_t set 
    )
    -     		-inlinestatic
    -
    - -

    Get the CPU set of processors that are physically close to device ibdev.

    -

    Store in set the CPU-set describing the locality of the OpenFabrics device ibdev (InfiniBand, etc).

    -

    Topology topology and device ibdev must match the local machine. I/O devices detection is not needed in the topology.

    -

    The function only returns the locality of the device. If more information about the device is needed, OS objects should be used instead, see hwloc_ibv_get_device_osdev() and hwloc_ibv_get_device_osdev_by_name().

    -

    This function is currently only implemented in a meaningful way for Linux; other systems will simply get a full cpuset.

    - -
    -
    - -

    ◆ hwloc_ibv_get_device_osdev()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_ibv_get_device_osdev (hwloc_topology_t topology,
    struct ibv_device * ibdev 
    )
    -     		-inlinestatic
    -
    - -

    Get the hwloc OS device object corresponding to the OpenFabrics device ibdev.

    -
    Returns
    The hwloc OS device object describing the OpenFabrics device ibdev (InfiniBand, etc).
    -
    -NULL if none could be found.
    -

    Topology topology and device ibdev must match the local machine. I/O devices detection must be enabled in the topology. If not, the locality of the object may still be found using hwloc_ibv_get_device_cpuset().

    -
    Note
    The corresponding PCI device object can be obtained by looking at the OS device parent object.
    - -
    -
    - -

    ◆ hwloc_ibv_get_device_osdev_by_name()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_ibv_get_device_osdev_by_name (hwloc_topology_t topology,
    const char * ibname 
    )
    -     		-inlinestatic
    -
    - -

    Get the hwloc OS device object corresponding to the OpenFabrics device named ibname.

    -
    Returns
    The hwloc OS device object describing the OpenFabrics device (InfiniBand, Omni-Path, usNIC, etc) whose name is ibname (mlx5_0, hfi1_0, usnic_0, qib0, etc).
    -
    -NULL if none could be found.
    -

    The name ibname is usually obtained from ibv_get_device_name().

    -

    The topology topology does not necessarily have to match the current machine. For instance the topology may be an XML import of a remote host. I/O devices detection must be enabled in the topology.

    -
    Note
    The corresponding PCI device object can be obtained by looking at the OS device parent object.
    - -
    -
    -
    - - - - - - - -
    -
    -Data Structures | -Typedefs | -Enumerations | -Functions
    -
    -
    Topology differences
    -
    -
    - - - - - - -

    -Data Structures

    union  hwloc_topology_diff_obj_attr_u
     
    union  hwloc_topology_diff_u
     
    - - - - - - - -

    -Typedefs

    typedef enum hwloc_topology_diff_obj_attr_type_e hwloc_topology_diff_obj_attr_type_t
     
    typedef enum hwloc_topology_diff_type_e hwloc_topology_diff_type_t
     
    typedef union hwloc_topology_diff_u * hwloc_topology_diff_t
     
    - - - - - - - -

    -Enumerations

    enum  hwloc_topology_diff_obj_attr_type_e { HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_SIZE -, HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_NAME -, HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_INFO - }
     
    enum  hwloc_topology_diff_type_e { HWLOC_TOPOLOGY_DIFF_OBJ_ATTR -, HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX - }
     
    enum  hwloc_topology_diff_apply_flags_e { HWLOC_TOPOLOGY_DIFF_APPLY_REVERSE - }
     
    - - - - - - - - - - - - - - - -

    -Functions

    int hwloc_topology_diff_build (hwloc_topology_t topology, hwloc_topology_t newtopology, unsigned long flags, hwloc_topology_diff_t *diff)
     
    int hwloc_topology_diff_apply (hwloc_topology_t topology, hwloc_topology_diff_t diff, unsigned long flags)
     
    int hwloc_topology_diff_destroy (hwloc_topology_diff_t diff)
     
    int hwloc_topology_diff_load_xml (const char *xmlpath, hwloc_topology_diff_t *diff, char **refname)
     
    int hwloc_topology_diff_export_xml (hwloc_topology_diff_t diff, const char *refname, const char *xmlpath)
     
    int hwloc_topology_diff_load_xmlbuffer (const char *xmlbuffer, int buflen, hwloc_topology_diff_t *diff, char **refname)
     
    int hwloc_topology_diff_export_xmlbuffer (hwloc_topology_diff_t diff, const char *refname, char **xmlbuffer, int *buflen)
     
    -

    Detailed Description

    -

    Applications that manipulate many similar topologies, for instance one for each node of a homogeneous cluster, may want to compress topologies to reduce the memory footprint.

    -

    This file offers a way to manipulate the difference between topologies and export/import it to/from XML. Compression may therefore be achieved by storing one topology entirely while the others are only described by their differences with the former. The actual topology can be reconstructed when actually needed by applying the precomputed difference to the reference topology.

    -

    This interface targets very similar nodes. Only very simple differences between topologies are actually supported, for instance a change in the memory size, the name of the object, or some info attribute. More complex differences such as adding or removing objects cannot be represented in the difference structures and therefore return errors. Differences between object sets or topology-wide allowed sets, cannot be represented either.

    -

    It means that there is no need to apply the difference when looking at the tree organization (how many levels, how many objects per level, what kind of objects, CPU and node sets, etc) and when binding to objects. However the difference must be applied when looking at object attributes such as the name, the memory size or info attributes.

    -

    Typedef Documentation

    - -

    ◆ hwloc_topology_diff_obj_attr_type_t

    - -
    -
    - - - - -
    typedef enum hwloc_topology_diff_obj_attr_type_e hwloc_topology_diff_obj_attr_type_t
    -
    - -

    Type of one object attribute difference.

    - -
    -
    - -

    ◆ hwloc_topology_diff_t

    - -
    -
    - - - - -
    typedef union hwloc_topology_diff_u * hwloc_topology_diff_t
    -
    - -

    One element of a difference list between two topologies.

    - -
    -
    - -

    ◆ hwloc_topology_diff_type_t

    - -
    -
    - - - - -
    typedef enum hwloc_topology_diff_type_e hwloc_topology_diff_type_t
    -
    - -

    Type of one element of a difference list.

    - -
    -
    -

    Enumeration Type Documentation

    - -

    ◆ hwloc_topology_diff_apply_flags_e

    - -
    -
    - - - - -
    enum hwloc_topology_diff_apply_flags_e
    -
    - -

    Flags to be given to hwloc_topology_diff_apply().

    - - -
    Enumerator
    HWLOC_TOPOLOGY_DIFF_APPLY_REVERSE 

    Apply topology diff in reverse direction.

    -
    - -
    -
    - -

    ◆ hwloc_topology_diff_obj_attr_type_e

    - -
    -
    - - - - -
    enum hwloc_topology_diff_obj_attr_type_e
    -
    - -

    Type of one object attribute difference.

    - - - - -
    Enumerator
    HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_SIZE 

    The object local memory is modified. The union is a hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s (and the index field is ignored).

    -
    HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_NAME 

    The object name is modified. The union is a hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s (and the name field is ignored).

    -
    HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_INFO 

    the value of an info attribute is modified. The union is a hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s.

    -
    - -
    -
    - -

    ◆ hwloc_topology_diff_type_e

    - -
    -
    - - - - -
    enum hwloc_topology_diff_type_e
    -
    - -

    Type of one element of a difference list.

    - - - -
    Enumerator
    HWLOC_TOPOLOGY_DIFF_OBJ_ATTR 

    An object attribute was changed. The union is a hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s.

    -
    HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX 

    The difference is too complex, it cannot be represented. The difference below this object has not been checked. hwloc_topology_diff_build() will return 1.

    -

    The union is a hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s.

    -
    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_topology_diff_apply()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_diff_apply (hwloc_topology_t topology,
    hwloc_topology_diff_t diff,
    unsigned long flags 
    )
    -
    - -

    Apply a topology diff to an existing topology.

    -

    flags is an OR'ed set of hwloc_topology_diff_apply_flags_e.

    -

    The new topology is modified in place. hwloc_topology_dup() may be used to duplicate it before patching.

    -

    If the difference cannot be applied entirely, all previous applied elements are unapplied before returning.

    -
    Returns
    0 on success.
    -
    --N if applying the difference failed while trying to apply the N-th part of the difference. For instance -1 is returned if the very first difference element could not be applied.
    - -
    -
    - -

    ◆ hwloc_topology_diff_build()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_diff_build (hwloc_topology_t topology,
    hwloc_topology_t newtopology,
    unsigned long flags,
    hwloc_topology_diff_t * diff 
    )
    -
    - -

    Compute the difference between 2 topologies.

    -

    The difference is stored as a list of hwloc_topology_diff_t entries starting at diff. It is computed by doing a depth-first traversal of both topology trees simultaneously.

    -

    If the difference between 2 objects is too complex to be represented (for instance if some objects have different types, or different numbers of children), a special diff entry of type HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX is queued. The computation of the diff does not continue below these objects. So each such diff entry means that the difference between two subtrees could not be computed.

    -
    Returns
    0 if the difference can be represented properly.
    -
    -0 with diff pointing to NULL if there is no difference between the topologies.
    -
    -1 if the difference is too complex (see above). Some entries in the list will be of type HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX.
    -
    --1 on any other error.
    -
    Note
    flags is currently not used. It should be 0.
    -
    -The output diff has to be freed with hwloc_topology_diff_destroy().
    -
    -The output diff can only be exported to XML or passed to hwloc_topology_diff_apply() if 0 was returned, i.e. if no entry of type HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX is listed.
    -
    -The output diff may be modified by removing some entries from the list. The removed entries should be freed by passing them to to hwloc_topology_diff_destroy() (possible as another list).
    - -
    -
    - -

    ◆ hwloc_topology_diff_destroy()

    - -
    -
    - - - - - - - - -
    int hwloc_topology_diff_destroy (hwloc_topology_diff_t diff)
    -
    - -

    Destroy a list of topology differences.

    - -
    -
    - -

    ◆ hwloc_topology_diff_export_xml()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_diff_export_xml (hwloc_topology_diff_t diff,
    const char * refname,
    const char * xmlpath 
    )
    -
    - -

    Export a list of topology differences to a XML file.

    -

    If not NULL, refname defines an identifier string for the reference topology which was used as a base when computing this difference. This identifier is usually the name of the other XML file that contains the reference topology. This attribute is given back when reading the diff from XML.

    - -
    -
    - -

    ◆ hwloc_topology_diff_export_xmlbuffer()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_diff_export_xmlbuffer (hwloc_topology_diff_t diff,
    const char * refname,
    char ** xmlbuffer,
    int * buflen 
    )
    -
    - -

    Export a list of topology differences to a XML buffer.

    -

    If not NULL, refname defines an identifier string for the reference topology which was used as a base when computing this difference. This identifier is usually the name of the other XML file that contains the reference topology. This attribute is given back when reading the diff from XML.

    -

    The returned buffer ends with a \0 that is included in the returned length.

    -
    Note
    The XML buffer should later be freed with hwloc_free_xmlbuffer().
    - -
    -
    - -

    ◆ hwloc_topology_diff_load_xml()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_diff_load_xml (const char * xmlpath,
    hwloc_topology_diff_t * diff,
    char ** refname 
    )
    -
    - -

    Load a list of topology differences from a XML file.

    -

    If not NULL, refname will be filled with the identifier string of the reference topology for the difference file, if any was specified in the XML file. This identifier is usually the name of the other XML file that contains the reference topology.

    -
    Note
    the pointer returned in refname should later be freed by the caller.
    - -
    -
    - -

    ◆ hwloc_topology_diff_load_xmlbuffer()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_diff_load_xmlbuffer (const char * xmlbuffer,
    int buflen,
    hwloc_topology_diff_t * diff,
    char ** refname 
    )
    -
    - -

    Load a list of topology differences from a XML buffer.

    -

    If not NULL, refname will be filled with the identifier string of the reference topology for the difference file, if any was specified in the XML file. This identifier is usually the name of the other XML file that contains the reference topology.

    -
    Note
    the pointer returned in refname should later be freed by the caller.
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    -
    Sharing topologies between processes
    -
    -
    - - - - - - - - -

    -Functions

    int hwloc_shmem_topology_get_length (hwloc_topology_t topology, size_t *lengthp, unsigned long flags)
     
    int hwloc_shmem_topology_write (hwloc_topology_t topology, int fd, hwloc_uint64_t fileoffset, void *mmap_address, size_t length, unsigned long flags)
     
    int hwloc_shmem_topology_adopt (hwloc_topology_t *topologyp, int fd, hwloc_uint64_t fileoffset, void *mmap_address, size_t length, unsigned long flags)
     
    -

    Detailed Description

    -

    These functions are used to share a topology between processes by duplicating it into a file-backed shared-memory buffer.

    -

    The master process must first get the required shared-memory size for storing this topology with hwloc_shmem_topology_get_length().

    -

    Then it must find a virtual memory area of that size that is available in all processes (identical virtual addresses in all processes). On Linux, this can be done by comparing holes found in /proc/<pid>/maps for each process.

    -

    Once found, it must open a destination file for storing the buffer, and pass it to hwloc_shmem_topology_write() together with virtual memory address and length obtained above.

    -

    Other processes may then adopt this shared topology by opening the same file and passing it to hwloc_shmem_topology_adopt() with the exact same virtual memory address and length.

    -

    Function Documentation

    - -

    ◆ hwloc_shmem_topology_adopt()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_shmem_topology_adopt (hwloc_topology_t * topologyp,
    int fd,
    hwloc_uint64_t fileoffset,
    void * mmap_address,
    size_t length,
    unsigned long flags 
    )
    -
    - -

    Adopt a shared memory topology stored in a file.

    -

    Map a file in virtual memory and adopt the topology that was previously stored there with hwloc_shmem_topology_write().

    -

    The returned adopted topology in topologyp can be used just like any topology. And it must be destroyed with hwloc_topology_destroy() as usual.

    -

    However the topology is read-only. For instance, it cannot be modified with hwloc_topology_restrict() and object userdata pointers cannot be changed.

    -

    The segment of the file pointed by descriptor fd, starting at offset fileoffset, and of length length (in bytes), will be mapped at virtual address mmap_address.

    -

    The file pointed by descriptor fd, the offset fileoffset, the requested mapping virtual address mmap_address and the length length must be identical to what was given to hwloc_shmem_topology_write() earlier.

    -
    Note
    Flags flags are currently unused, must be 0.
    -
    -The object userdata pointer should not be used unless the process that created the shared topology also placed userdata-pointed buffers in shared memory.
    -
    -This function takes care of calling hwloc_topology_abi_check().
    -
    Returns
    -1 with errno set to EBUSY if the virtual memory mapping defined by mmap_address and length isn't available in the process.
    -
    --1 with errno set to EINVAL if fileoffset, mmap_address or length aren't page-aligned, or do not match what was given to hwloc_shmem_topology_write() earlier.
    -
    --1 with errno set to EINVAL if the layout of the topology structure is different between the writer process and the adopter process.
    - -
    -
    - -

    ◆ hwloc_shmem_topology_get_length()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_shmem_topology_get_length (hwloc_topology_t topology,
    size_t * lengthp,
    unsigned long flags 
    )
    -
    - -

    Get the required shared memory length for storing a topology.

    -

    This length (in bytes) must be used in hwloc_shmem_topology_write() and hwloc_shmem_topology_adopt() later.

    -
    Note
    Flags flags are currently unused, must be 0.
    - -
    -
    - -

    ◆ hwloc_shmem_topology_write()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_shmem_topology_write (hwloc_topology_t topology,
    int fd,
    hwloc_uint64_t fileoffset,
    void * mmap_address,
    size_t length,
    unsigned long flags 
    )
    -
    - -

    Duplicate a topology to a shared memory file.

    -

    Temporarily map a file in virtual memory and duplicate the topology topology by allocating duplicates in there.

    -

    The segment of the file pointed by descriptor fd, starting at offset fileoffset, and of length length (in bytes), will be temporarily mapped at virtual address mmap_address during the duplication.

    -

    The mapping length length must have been previously obtained with hwloc_shmem_topology_get_length() and the topology must not have been modified in the meantime.

    -
    Note
    Flags flags are currently unused, must be 0.
    -
    -The object userdata pointer is duplicated but the pointed buffer is not. However the caller may also allocate it manually in shared memory to share it as well.
    -
    Returns
    -1 with errno set to EBUSY if the virtual memory mapping defined by mmap_address and length isn't available in the process.
    -
    --1 with errno set to EINVAL if fileoffset, mmap_address or length aren't page-aligned.
    - -
    -
    -
    - - - - - - - -
    -
    -Data Structures
    -
    -
    Components and Plugins: Discovery components
    -
    -
    - - - - -

    -Data Structures

    struct  hwloc_disc_component
     
    -

    Detailed Description

    -
    Note
    These structures and functions may change when HWLOC_COMPONENT_ABI is modified.
    -
    - - - - - - - -
    -
    -Data Structures | -Typedefs | -Enumerations | -Functions
    -
    -
    Components and Plugins: Discovery backends
    -
    -
    - - - - - - -

    -Data Structures

    struct  hwloc_disc_status
     
    struct  hwloc_backend
     
    - - - -

    -Typedefs

    typedef enum hwloc_disc_phase_e hwloc_disc_phase_t
     
    - - - - - -

    -Enumerations

    enum  hwloc_disc_phase_e {
    -  HWLOC_DISC_PHASE_GLOBAL -, HWLOC_DISC_PHASE_CPU -, HWLOC_DISC_PHASE_MEMORY -, HWLOC_DISC_PHASE_PCI -,
    -  HWLOC_DISC_PHASE_IO -, HWLOC_DISC_PHASE_MISC -, HWLOC_DISC_PHASE_ANNOTATE -, HWLOC_DISC_PHASE_TWEAK -
    - }
     
    enum  hwloc_disc_status_flag_e { HWLOC_DISC_STATUS_FLAG_GOT_ALLOWED_RESOURCES - }
     
    - - - - - -

    -Functions

    struct hwloc_backend * hwloc_backend_alloc (struct hwloc_topology *topology, struct hwloc_disc_component *component)
     
    int hwloc_backend_enable (struct hwloc_backend *backend)
     
    -

    Detailed Description

    -
    Note
    These structures and functions may change when HWLOC_COMPONENT_ABI is modified.
    -

    Typedef Documentation

    - -

    ◆ hwloc_disc_phase_t

    - -
    -
    - - - - -
    typedef enum hwloc_disc_phase_e hwloc_disc_phase_t
    -
    - -

    Discovery phase.

    - -
    -
    -

    Enumeration Type Documentation

    - -

    ◆ hwloc_disc_phase_e

    - -
    -
    - - - - -
    enum hwloc_disc_phase_e
    -
    - -

    Discovery phase.

    - - - - - - - - - -
    Enumerator
    HWLOC_DISC_PHASE_GLOBAL 

    xml or synthetic, platform-specific components such as bgq. Discovers everything including CPU, memory, I/O and everything else. A component with a Global phase usually excludes all other phases.

    -
    HWLOC_DISC_PHASE_CPU 

    CPU discovery.

    -
    HWLOC_DISC_PHASE_MEMORY 

    Attach memory to existing CPU objects.

    -
    HWLOC_DISC_PHASE_PCI 

    Attach PCI devices and bridges to existing CPU objects.

    -
    HWLOC_DISC_PHASE_IO 

    I/O discovery that requires PCI devices (OS devices such as OpenCL, CUDA, etc.).

    -
    HWLOC_DISC_PHASE_MISC 

    Misc objects that gets added below anything else.

    -
    HWLOC_DISC_PHASE_ANNOTATE 

    Annotating existing objects, adding distances, etc.

    -
    HWLOC_DISC_PHASE_TWEAK 

    Final tweaks to a ready-to-use topology. This phase runs once the topology is loaded, before it is returned to the topology. Hence it may only use the main hwloc API for modifying the topology, for instance by restricting it, adding info attributes, etc.

    -
    - -
    -
    - -

    ◆ hwloc_disc_status_flag_e

    - -
    -
    - - - - -
    enum hwloc_disc_status_flag_e
    -
    - -

    Discovery status flags.

    - - -
    Enumerator
    HWLOC_DISC_STATUS_FLAG_GOT_ALLOWED_RESOURCES 

    The sets of allowed resources were already retrieved.

    -
    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_backend_alloc()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    struct hwloc_backend* hwloc_backend_alloc (struct hwloc_topology * topology,
    struct hwloc_disc_component * component 
    )
    -
    - -

    Allocate a backend structure, set good default values, initialize backend->component and topology, etc. The caller will then modify whatever needed, and call hwloc_backend_enable().

    - -
    -
    - -

    ◆ hwloc_backend_enable()

    - -
    -
    - - - - - - - - -
    int hwloc_backend_enable (struct hwloc_backend * backend)
    -
    - -

    Enable a previously allocated and setup backend.

    - -
    -
    -
    - - - - - - - -
    -
    -Data Structures | -Typedefs | -Enumerations
    -
    -
    Components and Plugins: Generic components
    -
    -
    - - - - -

    -Data Structures

    struct  hwloc_component
     
    - - - -

    -Typedefs

    typedef enum hwloc_component_type_e hwloc_component_type_t
     
    - - - -

    -Enumerations

    enum  hwloc_component_type_e { HWLOC_COMPONENT_TYPE_DISC -, HWLOC_COMPONENT_TYPE_XML - }
     
    -

    Detailed Description

    -
    Note
    These structures and functions may change when HWLOC_COMPONENT_ABI is modified.
    -

    Typedef Documentation

    - -

    ◆ hwloc_component_type_t

    - -
    -
    - - - - -
    typedef enum hwloc_component_type_e hwloc_component_type_t
    -
    - -

    Generic component type.

    - -
    -
    -

    Enumeration Type Documentation

    - -

    ◆ hwloc_component_type_e

    - -
    -
    - - - - -
    enum hwloc_component_type_e
    -
    - -

    Generic component type.

    - - - -
    Enumerator
    HWLOC_COMPONENT_TYPE_DISC 

    The data field must point to a struct hwloc_disc_component.

    -
    HWLOC_COMPONENT_TYPE_XML 

    The data field must point to a struct hwloc_xml_component.

    -
    - -
    -
    -
    - - - - - - - -
    -
    -Macros | -Functions
    -
    -
    Components and Plugins: Core functions to be used by components
    -
    -
    - - - - - - -

    -Macros

    #define HWLOC_SHOW_CRITICAL_ERRORS()   (hwloc_hide_errors() < 2)
     
    #define HWLOC_SHOW_ALL_ERRORS()   (hwloc_hide_errors() == 0)
     
    - - - - - - - - - - - - - - - -

    -Functions

    int hwloc_hide_errors (void)
     
    hwloc_obj_t hwloc__insert_object_by_cpuset (struct hwloc_topology *topology, hwloc_obj_t root, hwloc_obj_t obj, const char *reason)
     
    void hwloc_insert_object_by_parent (struct hwloc_topology *topology, hwloc_obj_t parent, hwloc_obj_t obj)
     
    hwloc_obj_t hwloc_alloc_setup_object (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned os_index)
     
    int hwloc_obj_add_children_sets (hwloc_obj_t obj)
     
    int hwloc_topology_reconnect (hwloc_topology_t topology, unsigned long flags)
     
    static int hwloc_plugin_check_namespace (const char *pluginname, const char *symbol)
     
    -

    Detailed Description

    -
    Note
    These structures and functions may change when HWLOC_COMPONENT_ABI is modified.
    -

    Macro Definition Documentation

    - -

    ◆ HWLOC_SHOW_ALL_ERRORS

    - -
    -
    - - - - - - - -
    #define HWLOC_SHOW_ALL_ERRORS()   (hwloc_hide_errors() == 0)
    -
    - -
    -
    - -

    ◆ HWLOC_SHOW_CRITICAL_ERRORS

    - -
    -
    - - - - - - - -
    #define HWLOC_SHOW_CRITICAL_ERRORS()   (hwloc_hide_errors() < 2)
    -
    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc__insert_object_by_cpuset()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    hwloc_obj_t hwloc__insert_object_by_cpuset (struct hwloc_topology * topology,
    hwloc_obj_t root,
    hwloc_obj_t obj,
    const char * reason 
    )
    -
    - -

    Add an object to the topology.

    -

    Insert new object obj in the topology starting under existing object root (if NULL, the topology root object is used).

    -

    It is sorted along the tree of other objects according to the inclusion of cpusets, to eventually be added as a child of the smallest object including this object.

    -

    If the cpuset is empty, the type of the object (and maybe some attributes) must be enough to find where to insert the object. This is especially true for NUMA nodes with memory and no CPUs.

    -

    The given object should not have children.

    -

    This shall only be called before levels are built.

    -

    The caller should check whether the object type is filtered-out before calling this function.

    -

    The topology cpuset/nodesets will be enlarged to include the object sets.

    -

    reason is a unique string identifying where and why this insertion call was performed (it will be displayed in case of internal insertion error).

    -

    Returns the object on success. Returns NULL and frees obj on error. Returns another object and frees obj if it was merged with an identical pre-existing object.

    - -
    -
    - -

    ◆ hwloc_alloc_setup_object()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    hwloc_obj_t hwloc_alloc_setup_object (hwloc_topology_t topology,
    hwloc_obj_type_t type,
    unsigned os_index 
    )
    -
    - -

    Allocate and initialize an object of the given type and physical index.

    -

    If os_index is unknown or irrelevant, use HWLOC_UNKNOWN_INDEX.

    - -
    -
    - -

    ◆ hwloc_hide_errors()

    - -
    -
    - - - - - - - - -
    int hwloc_hide_errors (void )
    -
    - -

    Check whether error messages are hidden.

    -

    Callers should print critical error messages (e.g. invalid hw topo info, invalid config) only if this function returns strictly less than 2.

    -

    Callers should print non-critical error messages (e.g. failure to initialize CUDA) if this function returns 0.

    -

    This function return 1 by default (show critical only), 0 in lstopo (show all), or anything set in HWLOC_HIDE_ERRORS in the environment.

    -

    Use macros HWLOC_SHOW_CRITICAL_ERRORS() and HWLOC_SHOW_ALL_ERRORS() for clarity.

    - -
    -
    - -

    ◆ hwloc_insert_object_by_parent()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    void hwloc_insert_object_by_parent (struct hwloc_topology * topology,
    hwloc_obj_t parent,
    hwloc_obj_t obj 
    )
    -
    - -

    Insert an object somewhere in the topology.

    -

    It is added as the last child of the given parent. The cpuset is completely ignored, so strange objects such as I/O devices should preferably be inserted with this.

    -

    When used for "normal" children with cpusets (when importing from XML when duplicating a topology), the caller should make sure that:

      -
    • children are inserted in order,
      • -
    • children cpusets do not intersect.
      • -
    -

    The given object may have normal, I/O or Misc children, as long as they are in order as well. These children must have valid parent and next_sibling pointers.

    -

    The caller should check whether the object type is filtered-out before calling this function.

    - -
    -
    - -

    ◆ hwloc_obj_add_children_sets()

    - -
    -
    - - - - - - - - -
    int hwloc_obj_add_children_sets (hwloc_obj_t obj)
    -
    - -

    Setup object cpusets/nodesets by OR'ing its children.

    -

    Used when adding an object late in the topology. Will update the new object by OR'ing all its new children sets.

    -

    Used when PCI backend adds a hostbridge parent, when distances add a new Group, etc.

    - -
    -
    - -

    ◆ hwloc_plugin_check_namespace()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static int hwloc_plugin_check_namespace (const char * pluginname,
    const char * symbol 
    )
    -     		-inlinestatic
    -
    - -

    Make sure that plugins can lookup core symbols.

    -

    This is a sanity check to avoid lazy-lookup failures when libhwloc is loaded within a plugin, and later tries to load its own plugins. This may fail (and abort the program) if libhwloc symbols are in a private namespace.

    -
    Returns
    0 on success.
    -
    --1 if the plugin cannot be successfully loaded. The caller plugin init() callback should return a negative error code as well.
    -

    Plugins should call this function in their init() callback to avoid later crashes if lazy symbol resolution is used by the upper layer that loaded hwloc (e.g. OpenCL implementations using dlopen with RTLD_LAZY).

    -
    Note
    The build system must define HWLOC_INSIDE_PLUGIN if and only if building the caller as a plugin.
    -
    -This function should remain inline so plugins can call it even when they cannot find libhwloc symbols.
    - -
    -
    - -

    ◆ hwloc_topology_reconnect()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_reconnect (hwloc_topology_t topology,
    unsigned long flags 
    )
    -
    - -

    Request a reconnection of children and levels in the topology.

    -

    May be used by backends during discovery if they need arrays or lists of object within levels or children to be fully connected.

    -

    flags is currently unused, must 0.

    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    -
    Components and Plugins: Filtering objects
    -
    -
    - - - - - - - - - - -

    -Functions

    static int hwloc_filter_check_pcidev_subtype_important (unsigned classid)
     
    static int hwloc_filter_check_osdev_subtype_important (hwloc_obj_osdev_type_t subtype)
     
    static int hwloc_filter_check_keep_object_type (hwloc_topology_t topology, hwloc_obj_type_t type)
     
    static int hwloc_filter_check_keep_object (hwloc_topology_t topology, hwloc_obj_t obj)
     
    -

    Detailed Description

    -
    Note
    These structures and functions may change when HWLOC_COMPONENT_ABI is modified.
    -

    Function Documentation

    - -

    ◆ hwloc_filter_check_keep_object()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static int hwloc_filter_check_keep_object (hwloc_topology_t topology,
    hwloc_obj_t obj 
    )
    -     		-inlinestatic
    -
    - -

    Check whether the given object should be filtered-out.

    -
    Returns
    1 if the object type should be kept, 0 otherwise.
    - -
    -
    - -

    ◆ hwloc_filter_check_keep_object_type()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static int hwloc_filter_check_keep_object_type (hwloc_topology_t topology,
    hwloc_obj_type_t type 
    )
    -     		-inlinestatic
    -
    - -

    Check whether a non-I/O object type should be filtered-out.

    -

    Cannot be used for I/O objects.

    -
    Returns
    1 if the object type should be kept, 0 otherwise.
    - -
    -
    - -

    ◆ hwloc_filter_check_osdev_subtype_important()

    - -
    -
    - - - - - -
    - - - - - - - - -
    static int hwloc_filter_check_osdev_subtype_important (hwloc_obj_osdev_type_t subtype)
    -     		-inlinestatic
    -
    - -

    Check whether the given OS device subtype is important.

    -
    Returns
    1 if important, 0 otherwise.
    - -
    -
    - -

    ◆ hwloc_filter_check_pcidev_subtype_important()

    - -
    -
    - - - - - -
    - - - - - - - - -
    static int hwloc_filter_check_pcidev_subtype_important (unsigned classid)
    -     		-inlinestatic
    -
    - -

    Check whether the given PCI device classid is important.

    -
    Returns
    1 if important, 0 otherwise.
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    -
    Components and Plugins: helpers for PCI discovery
    -
    -
    - - - - - - - - - - - - - - -

    -Functions

    unsigned hwloc_pcidisc_find_cap (const unsigned char *config, unsigned cap)
     
    int hwloc_pcidisc_find_linkspeed (const unsigned char *config, unsigned offset, float *linkspeed)
     
    hwloc_obj_type_t hwloc_pcidisc_check_bridge_type (unsigned device_class, const unsigned char *config)
     
    int hwloc_pcidisc_find_bridge_buses (unsigned domain, unsigned bus, unsigned dev, unsigned func, unsigned *secondary_busp, unsigned *subordinate_busp, const unsigned char *config)
     
    void hwloc_pcidisc_tree_insert_by_busid (struct hwloc_obj **treep, struct hwloc_obj *obj)
     
    int hwloc_pcidisc_tree_attach (struct hwloc_topology *topology, struct hwloc_obj *tree)
     
    -

    Detailed Description

    -
    Note
    These structures and functions may change when HWLOC_COMPONENT_ABI is modified.
    -

    Function Documentation

    - -

    ◆ hwloc_pcidisc_check_bridge_type()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    hwloc_obj_type_t hwloc_pcidisc_check_bridge_type (unsigned device_class,
    const unsigned char * config 
    )
    -
    - -

    Return the hwloc object type (PCI device or Bridge) for the given class and configuration space.

    -

    This function requires 16 bytes of common configuration header at the beginning of config.

    - -
    -
    - -

    ◆ hwloc_pcidisc_find_bridge_buses()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_pcidisc_find_bridge_buses (unsigned domain,
    unsigned bus,
    unsigned dev,
    unsigned func,
    unsigned * secondary_busp,
    unsigned * subordinate_busp,
    const unsigned char * config 
    )
    -
    - -

    Fills the attributes of the given PCI bridge using the given PCI config space.

    -

    This function requires 32 bytes of common configuration header at the beginning of config.

    -

    Returns -1 and destroys /p obj if bridge fields are invalid.

    - -
    -
    - -

    ◆ hwloc_pcidisc_find_cap()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    unsigned hwloc_pcidisc_find_cap (const unsigned char * config,
    unsigned cap 
    )
    -
    - -

    Return the offset of the given capability in the PCI config space buffer.

    -

    This function requires a 256-bytes config space. Unknown/unavailable bytes should be set to 0xff.

    - -
    -
    - -

    ◆ hwloc_pcidisc_find_linkspeed()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_pcidisc_find_linkspeed (const unsigned char * config,
    unsigned offset,
    float * linkspeed 
    )
    -
    - -

    Fill linkspeed by reading the PCI config space where PCI_CAP_ID_EXP is at position offset.

    -

    Needs 20 bytes of EXP capability block starting at offset in the config space for registers up to link status.

    - -
    -
    - -

    ◆ hwloc_pcidisc_tree_attach()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_pcidisc_tree_attach (struct hwloc_topology * topology,
    struct hwloc_obj * tree 
    )
    -
    - -

    Add some hostbridges on top of the given tree of PCI objects and attach them to the topology.

    -

    Other backends may lookup PCI objects or localities (for instance to attach OS devices) by using hwloc_pcidisc_find_by_busid() or hwloc_pcidisc_find_busid_parent().

    - -
    -
    - -

    ◆ hwloc_pcidisc_tree_insert_by_busid()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    void hwloc_pcidisc_tree_insert_by_busid (struct hwloc_obj ** treep,
    struct hwloc_obj * obj 
    )
    -
    - -

    Insert a PCI object in the given PCI tree by looking at PCI bus IDs.

    -

    If treep points to NULL, the new object is inserted there.

    - -
    -
    -
    - - - - - - - -
    -
    -Typedefs | -Functions
    -
    -
    Components and Plugins: finding PCI objects during other discoveries
    -
    -
    - - - - -

    -Typedefs

    typedef void * hwloc_backend_distances_add_handle_t
     
    - - - - - - - - - - - -

    -Functions

    struct hwloc_obj * hwloc_pci_find_parent_by_busid (struct hwloc_topology *topology, unsigned domain, unsigned bus, unsigned dev, unsigned func)
     
    struct hwloc_obj * hwloc_pci_find_by_busid (struct hwloc_topology *topology, unsigned domain, unsigned bus, unsigned dev, unsigned func)
     
    hwloc_backend_distances_add_handle_t hwloc_backend_distances_add_create (hwloc_topology_t topology, const char *name, unsigned long kind, unsigned long flags)
     
    int hwloc_backend_distances_add_values (hwloc_topology_t topology, hwloc_backend_distances_add_handle_t handle, unsigned nbobjs, hwloc_obj_t *objs, hwloc_uint64_t *values, unsigned long flags)
     
    int hwloc_backend_distances_add_commit (hwloc_topology_t topology, hwloc_backend_distances_add_handle_t handle, unsigned long flags)
     
    -

    Detailed Description

    -
    Note
    These structures and functions may change when HWLOC_COMPONENT_ABI is modified.
    -

    Typedef Documentation

    - -

    ◆ hwloc_backend_distances_add_handle_t

    - -
    -
    - - - - -
    typedef void* hwloc_backend_distances_add_handle_t
    -
    - -

    Handle to a new distances structure during its addition to the topology.

    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_backend_distances_add_commit()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_backend_distances_add_commit (hwloc_topology_t topology,
    hwloc_backend_distances_add_handle_t handle,
    unsigned long flags 
    )
    -
    - -

    Commit a new distances structure.

    -

    This is similar to hwloc_distances_add_commit() but this variant is designed for backend inserting distances during topology discovery.

    - -
    -
    - -

    ◆ hwloc_backend_distances_add_create()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    hwloc_backend_distances_add_handle_t hwloc_backend_distances_add_create (hwloc_topology_t topology,
    const char * name,
    unsigned long kind,
    unsigned long flags 
    )
    -
    - -

    Create a new empty distances structure.

    -

    This is identical to hwloc_distances_add_create() but this variant is designed for backend inserting distances during topology discovery.

    - -
    -
    - -

    ◆ hwloc_backend_distances_add_values()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_backend_distances_add_values (hwloc_topology_t topology,
    hwloc_backend_distances_add_handle_t handle,
    unsigned nbobjs,
    hwloc_obj_t * objs,
    hwloc_uint64_t * values,
    unsigned long flags 
    )
    -
    - -

    Specify the objects and values in a new empty distances structure.

    -

    This is similar to hwloc_distances_add_values() but this variant is designed for backend inserting distances during topology discovery.

    -

    The only semantical difference is that objs and values are not duplicated, but directly attached to the topology. On success, these arrays are given to the core and should not ever be freed by the caller anymore.

    - -
    -
    - -

    ◆ hwloc_pci_find_by_busid()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    struct hwloc_obj* hwloc_pci_find_by_busid (struct hwloc_topology * topology,
    unsigned domain,
    unsigned bus,
    unsigned dev,
    unsigned func 
    )
    -
    - -

    Find the PCI device or bridge matching a PCI bus ID exactly.

    -

    This is useful for adding specific information about some objects based on their PCI id. When it comes to attaching objects based on PCI locality, hwloc_pci_find_parent_by_busid() should be preferred.

    - -
    -
    - -

    ◆ hwloc_pci_find_parent_by_busid()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    struct hwloc_obj* hwloc_pci_find_parent_by_busid (struct hwloc_topology * topology,
    unsigned domain,
    unsigned bus,
    unsigned dev,
    unsigned func 
    )
    -
    - -

    Find the object or a parent of a PCI bus ID.

    -

    When attaching a new object (typically an OS device) whose locality is specified by PCI bus ID, this function returns the PCI object to use as a parent for attaching.

    -

    If the exact PCI device with this bus ID exists, it is returned. Otherwise (for instance if it was filtered out), the function returns another object with similar locality (for instance a parent bridge, or the local CPU Package).

    - -
    -
    -
    - - - - - - - -
    -
    -Enumerations
    -
    -
    Netloc API
    -
    -
    - - - - -

    -Enumerations

    enum  {
    -  NETLOC_SUCCESS = 0 -, NETLOC_ERROR = -1 -, NETLOC_ERROR_NOTDIR = -2 -, NETLOC_ERROR_NOENT = -3 -,
    -  NETLOC_ERROR_EMPTY = -4 -, NETLOC_ERROR_MULTIPLE = -5 -, NETLOC_ERROR_NOT_IMPL = -6 -, NETLOC_ERROR_EXISTS = -7 -,
    -  NETLOC_ERROR_NOT_FOUND = -8 -, NETLOC_ERROR_MAX = -9 -
    - }
     
    -

    Detailed Description

    -

    Enumeration Type Documentation

    - -

    ◆ anonymous enum

    - -
    -
    - - - - -
    anonymous enum
    -
    -

    Return codes

    - - - - - - - - - - - -
    Enumerator
    NETLOC_SUCCESS 

    Success

    -
    NETLOC_ERROR 

    Error: General condition

    -
    NETLOC_ERROR_NOTDIR 

    Error: URI is not a directory

    -
    NETLOC_ERROR_NOENT 

    Error: URI is invalid, no such entry

    -
    NETLOC_ERROR_EMPTY 

    Error: No networks found

    -
    NETLOC_ERROR_MULTIPLE 

    Error: Multiple matching networks found

    -
    NETLOC_ERROR_NOT_IMPL 

    Error: Interface not implemented

    -
    NETLOC_ERROR_EXISTS 

    Error: If the entry already exists when trying to add to a lookup table

    -
    NETLOC_ERROR_NOT_FOUND 

    Error: No path found

    -
    NETLOC_ERROR_MAX 

    Error: Enum upper bound marker. No errors less than this number Will not be returned externally.

    -
    - -
    -
    -
    - - - - - - - -
    -
    -Data Fields
    -
    -
    hwloc_obj Struct Reference
    Object Structure and Attributes
    -
    -
    - -

    #include <hwloc.h>

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

    -Data Fields

    hwloc_obj_type_t type
     
    char * subtype
     
    unsigned os_index
     
    char * name
     
    hwloc_uint64_t total_memory
     
    union hwloc_obj_attr_u * attr
     
    int depth
     
    unsigned logical_index
     
    struct hwloc_obj * next_cousin
     
    struct hwloc_obj * prev_cousin
     
    struct hwloc_obj * parent
     
    unsigned sibling_rank
     
    struct hwloc_obj * next_sibling
     
    struct hwloc_obj * prev_sibling
     
    int symmetric_subtree
     
    hwloc_cpuset_t cpuset
     
    hwloc_cpuset_t complete_cpuset
     
    hwloc_nodeset_t nodeset
     
    hwloc_nodeset_t complete_nodeset
     
    struct hwloc_info_s * infos
     
    unsigned infos_count
     
    void * userdata
     
    hwloc_uint64_t gp_index
     
    List and array of normal children below this object (except Memory, I/O and Misc children).
    unsigned arity
     
    struct hwloc_obj ** children
     
    struct hwloc_obj * first_child
     
    struct hwloc_obj * last_child
     
    List of Memory children below this object.
    unsigned memory_arity
     
    struct hwloc_obj * memory_first_child
     
    List of I/O children below this object.
    unsigned io_arity
     
    struct hwloc_obj * io_first_child
     
    List of Misc children below this object.
    unsigned misc_arity
     
    struct hwloc_obj * misc_first_child
     
    -

    Detailed Description

    -

    Structure of a topology object.

    -

    Applications must not modify any field except hwloc_obj.userdata.

    -

    Field Documentation

    - -

    ◆ arity

    - -
    -
    - - - - -
    unsigned hwloc_obj::arity
    -
    - -

    Number of normal children. Memory, Misc and I/O children are not listed here but rather in their dedicated children list.

    - -
    -
    - -

    ◆ attr

    - -
    -
    - - - - -
    union hwloc_obj_attr_u* hwloc_obj::attr
    -
    - -

    Object type-specific Attributes, may be NULL if no attribute value was found.

    - -
    -
    - -

    ◆ children

    - -
    -
    - - - - -
    struct hwloc_obj** hwloc_obj::children
    -
    - -

    Normal children, children[0 .. arity -1].

    - -
    -
    - -

    ◆ complete_cpuset

    - -
    -
    - - - - -
    hwloc_cpuset_t hwloc_obj::complete_cpuset
    -
    - -

    The complete CPU set of processors of this object,.

    -

    This may include not only the same as the cpuset field, but also some CPUs for which topology information is unknown or incomplete, some offlines CPUs, and the CPUs that are ignored when the HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED flag is not set. Thus no corresponding PU object may be found in the topology, because the precise position is undefined. It is however known that it would be somewhere under this object.

    -
    Note
    Its value must not be changed, hwloc_bitmap_dup() must be used instead.
    - -
    -
    - -

    ◆ complete_nodeset

    - -
    -
    - - - - -
    hwloc_nodeset_t hwloc_obj::complete_nodeset
    -
    - -

    The complete NUMA node set of this object,.

    -

    This may include not only the same as the nodeset field, but also some NUMA nodes for which topology information is unknown or incomplete, some offlines nodes, and the nodes that are ignored when the HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED flag is not set. Thus no corresponding NUMA node object may be found in the topology, because the precise position is undefined. It is however known that it would be somewhere under this object.

    -

    If there are no NUMA nodes in the machine, all the memory is close to this object, so only the first bit is set in complete_nodeset.

    -
    Note
    Its value must not be changed, hwloc_bitmap_dup() must be used instead.
    - -
    -
    - -

    ◆ cpuset

    - -
    -
    - - - - -
    hwloc_cpuset_t hwloc_obj::cpuset
    -
    - -

    CPUs covered by this object.

    -

    This is the set of CPUs for which there are PU objects in the topology under this object, i.e. which are known to be physically contained in this object and known how (the children path between this object and the PU objects).

    -

    If the HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED configuration flag is set, some of these CPUs may be online but not allowed for binding, see hwloc_topology_get_allowed_cpuset().

    -
    Note
    All objects have non-NULL CPU and node sets except Misc and I/O objects.
    -
    -Its value must not be changed, hwloc_bitmap_dup() must be used instead.
    - -
    -
    - -

    ◆ depth

    - -
    -
    - - - - -
    int hwloc_obj::depth
    -
    - -

    Vertical index in the hierarchy.

    -

    For normal objects, this is the depth of the horizontal level that contains this object and its cousins of the same type. If the topology is symmetric, this is equal to the parent depth plus one, and also equal to the number of parent/child links from the root object to here.

    -

    For special objects (NUMA nodes, I/O and Misc) that are not in the main tree, this is a special negative value that corresponds to their dedicated level, see hwloc_get_type_depth() and hwloc_get_type_depth_e. Those special values can be passed to hwloc functions such hwloc_get_nbobjs_by_depth() as usual.

    - -
    -
    - -

    ◆ first_child

    - -
    -
    - - - - -
    struct hwloc_obj* hwloc_obj::first_child
    -
    - -

    First normal child.

    - -
    -
    - -

    ◆ gp_index

    - -
    -
    - - - - -
    hwloc_uint64_t hwloc_obj::gp_index
    -
    - -

    Global persistent index. Generated by hwloc, unique across the topology (contrary to os_index) and persistent across topology changes (contrary to logical_index). Mostly used internally, but could also be used by application to identify objects.

    - -
    -
    - -

    ◆ infos

    - -
    -
    - - - - -
    struct hwloc_info_s* hwloc_obj::infos
    -
    - -

    Array of stringified info type=name.

    - -
    -
    - -

    ◆ infos_count

    - -
    -
    - - - - -
    unsigned hwloc_obj::infos_count
    -
    - -

    Size of infos array.

    - -
    -
    - -

    ◆ io_arity

    - -
    -
    - - - - -
    unsigned hwloc_obj::io_arity
    -
    - -

    Number of I/O children. These children are listed in io_first_child.

    - -
    -
    - -

    ◆ io_first_child

    - -
    -
    - - - - -
    struct hwloc_obj* hwloc_obj::io_first_child
    -
    - -

    First I/O child. Bridges, PCI and OS devices are listed here (io_arity and io_first_child) instead of in the normal children list. See also hwloc_obj_type_is_io().

    - -
    -
    - -

    ◆ last_child

    - -
    -
    - - - - -
    struct hwloc_obj* hwloc_obj::last_child
    -
    - -

    Last normal child.

    - -
    -
    - -

    ◆ logical_index

    - -
    -
    - - - - -
    unsigned hwloc_obj::logical_index
    -
    - -

    Horizontal index in the whole list of similar objects, hence guaranteed unique across the entire machine. Could be a "cousin_rank" since it's the rank within the "cousin" list below Note that this index may change when restricting the topology or when inserting a group.

    - -
    -
    - -

    ◆ memory_arity

    - -
    -
    - - - - -
    unsigned hwloc_obj::memory_arity
    -
    - -

    Number of Memory children. These children are listed in memory_first_child.

    - -
    -
    - -

    ◆ memory_first_child

    - -
    -
    - - - - -
    struct hwloc_obj* hwloc_obj::memory_first_child
    -
    - -

    First Memory child. NUMA nodes and Memory-side caches are listed here (memory_arity and memory_first_child) instead of in the normal children list. See also hwloc_obj_type_is_memory().

    -

    A memory hierarchy starts from a normal CPU-side object (e.g. Package) and ends with NUMA nodes as leaves. There might exist some memory-side caches between them in the middle of the memory subtree.

    - -
    -
    - -

    ◆ misc_arity

    - -
    -
    - - - - -
    unsigned hwloc_obj::misc_arity
    -
    - -

    Number of Misc children. These children are listed in misc_first_child.

    - -
    -
    - -

    ◆ misc_first_child

    - -
    -
    - - - - -
    struct hwloc_obj* hwloc_obj::misc_first_child
    -
    - -

    First Misc child. Misc objects are listed here (misc_arity and misc_first_child) instead of in the normal children list.

    - -
    -
    - -

    ◆ name

    - -
    -
    - - - - -
    char* hwloc_obj::name
    -
    - -

    Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name string is more useful than numerical indexes.

    - -
    -
    - -

    ◆ next_cousin

    - -
    -
    - - - - -
    struct hwloc_obj* hwloc_obj::next_cousin
    -
    - -

    Next object of same type and depth.

    - -
    -
    - -

    ◆ next_sibling

    - -
    -
    - - - - -
    struct hwloc_obj* hwloc_obj::next_sibling
    -
    - -

    Next object below the same parent (inside the same list of children).

    - -
    -
    - -

    ◆ nodeset

    - -
    -
    - - - - -
    hwloc_nodeset_t hwloc_obj::nodeset
    -
    - -

    NUMA nodes covered by this object or containing this object.

    -

    This is the set of NUMA nodes for which there are NUMA node objects in the topology under or above this object, i.e. which are known to be physically contained in this object or containing it and known how (the children path between this object and the NUMA node objects).

    -

    In the end, these nodes are those that are close to the current object. Function hwloc_get_local_numanode_objs() may be used to list those NUMA nodes more precisely.

    -

    If the HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED configuration flag is set, some of these nodes may be online but not allowed for allocation, see hwloc_topology_get_allowed_nodeset().

    -

    If there are no NUMA nodes in the machine, all the memory is close to this object, so only the first bit may be set in nodeset.

    -
    Note
    All objects have non-NULL CPU and node sets except Misc and I/O objects.
    -
    -Its value must not be changed, hwloc_bitmap_dup() must be used instead.
    - -
    -
    - -

    ◆ os_index

    - -
    -
    - - - - -
    unsigned hwloc_obj::os_index
    -
    - -

    OS-provided physical index number. It is not guaranteed unique across the entire machine, except for PUs and NUMA nodes. Set to HWLOC_UNKNOWN_INDEX if unknown or irrelevant for this object.

    - -
    -
    - -

    ◆ parent

    - -
    -
    - - - - -
    struct hwloc_obj* hwloc_obj::parent
    -
    - -

    Parent, NULL if root (Machine object)

    - -
    -
    - -

    ◆ prev_cousin

    - -
    -
    - - - - -
    struct hwloc_obj* hwloc_obj::prev_cousin
    -
    - -

    Previous object of same type and depth.

    - -
    -
    - -

    ◆ prev_sibling

    - -
    -
    - - - - -
    struct hwloc_obj* hwloc_obj::prev_sibling
    -
    - -

    Previous object below the same parent (inside the same list of children).

    - -
    -
    - -

    ◆ sibling_rank

    - -
    -
    - - - - -
    unsigned hwloc_obj::sibling_rank
    -
    - -

    Index in parent's children[] array. Or the index in parent's Memory, I/O or Misc children list.

    - -
    -
    - -

    ◆ subtype

    - -
    -
    - - - - -
    char* hwloc_obj::subtype
    -
    - -

    Subtype string to better describe the type field.

    - -
    -
    - -

    ◆ symmetric_subtree

    - -
    -
    - - - - -
    int hwloc_obj::symmetric_subtree
    -
    - -

    Set if the subtree of normal objects below this object is symmetric, which means all normal children and their children have identical subtrees.

    -

    Memory, I/O and Misc children are ignored.

    -

    If set in the topology root object, lstopo may export the topology as a synthetic string.

    - -
    -
    - -

    ◆ total_memory

    - -
    -
    - - - - -
    hwloc_uint64_t hwloc_obj::total_memory
    -
    - -

    Total memory (in bytes) in NUMA nodes below this object.

    - -
    -
    - -

    ◆ type

    - -
    -
    - - - - -
    hwloc_obj_type_t hwloc_obj::type
    -
    - -

    Type of object.

    - -
    -
    - -

    ◆ userdata

    - -
    -
    - - - - -
    void* hwloc_obj::userdata
    -
    - -

    Application-given private data pointer, initialized to NULL, use it as you wish. See hwloc_topology_set_userdata_export_callback() in hwloc/export.h if you wish to export this field to XML.

    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - -
    -
    -Data Structures | -Data Fields
    -
    -
    hwloc_obj_attr_u Union Reference
    Object Structure and Attributes
    -
    -
    - -

    #include <hwloc.h>

    - - - - - - - - - - - - - - -

    -Data Structures

    struct  hwloc_bridge_attr_s
     
    struct  hwloc_cache_attr_s
     
    struct  hwloc_group_attr_s
     
    struct  hwloc_numanode_attr_s
     
    struct  hwloc_osdev_attr_s
     
    struct  hwloc_pcidev_attr_s
     
    - - - - - - - - - - - - - -

    -Data Fields

    struct hwloc_obj_attr_u::hwloc_numanode_attr_s numanode
     
    struct hwloc_obj_attr_u::hwloc_cache_attr_s cache
     
    struct hwloc_obj_attr_u::hwloc_group_attr_s group
     
    struct hwloc_obj_attr_u::hwloc_pcidev_attr_s pcidev
     
    struct hwloc_obj_attr_u::hwloc_bridge_attr_s bridge
     
    struct hwloc_obj_attr_u::hwloc_osdev_attr_s osdev
     
    -

    Detailed Description

    -

    Object type-specific Attributes.

    -

    Field Documentation

    - -

    ◆ bridge

    - -
    -
    - - - - -
    struct hwloc_obj_attr_u::hwloc_bridge_attr_s hwloc_obj_attr_u::bridge
    -
    - -
    -
    - -

    ◆ cache

    - -
    -
    - - - - -
    struct hwloc_obj_attr_u::hwloc_cache_attr_s hwloc_obj_attr_u::cache
    -
    - -
    -
    - -

    ◆ group

    - -
    -
    - - - - -
    struct hwloc_obj_attr_u::hwloc_group_attr_s hwloc_obj_attr_u::group
    -
    - -
    -
    - -

    ◆ numanode

    - -
    -
    - - - - -
    struct hwloc_obj_attr_u::hwloc_numanode_attr_s hwloc_obj_attr_u::numanode
    -
    - -
    -
    - -

    ◆ osdev

    - -
    -
    - - - - -
    struct hwloc_obj_attr_u::hwloc_osdev_attr_s hwloc_obj_attr_u::osdev
    -
    - -
    -
    - -

    ◆ pcidev

    - -
    -
    - - - - -
    struct hwloc_obj_attr_u::hwloc_pcidev_attr_s hwloc_obj_attr_u::pcidev
    -
    - -
    -
    -
    The documentation for this union was generated from the following file: -
    - - - - - - - - -
    -
    -Data Structures | -Data Fields
    -
    -
    hwloc_obj_attr_u::hwloc_numanode_attr_s Struct Reference
    -
    -
    - -

    #include <hwloc.h>

    - - - - -

    -Data Structures

    struct  hwloc_memory_page_type_s
     
    - - - - - - - -

    -Data Fields

    hwloc_uint64_t local_memory
     
    unsigned page_types_len
     
    struct hwloc_obj_attr_u::hwloc_numanode_attr_s::hwloc_memory_page_type_s * page_types
     
    -

    Detailed Description

    -

    NUMA node-specific Object Attributes.

    -

    Field Documentation

    - -

    ◆ local_memory

    - -
    -
    - - - - -
    hwloc_uint64_t hwloc_obj_attr_u::hwloc_numanode_attr_s::local_memory
    -
    - -

    Local memory (in bytes)

    - -
    -
    - -

    ◆ page_types

    - -
    -
    - - - - -
    struct hwloc_obj_attr_u::hwloc_numanode_attr_s::hwloc_memory_page_type_s * hwloc_obj_attr_u::hwloc_numanode_attr_s::page_types
    -
    - -
    -
    - -

    ◆ page_types_len

    - -
    -
    - - - - -
    unsigned hwloc_obj_attr_u::hwloc_numanode_attr_s::page_types_len
    -
    - -

    Size of array page_types.

    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - - -
    -
    -Data Fields
    -
    -
    hwloc_obj_attr_u::hwloc_numanode_attr_s::hwloc_memory_page_type_s Struct Reference
    -
    -
    - -

    #include <hwloc.h>

    - - - - - - -

    -Data Fields

    hwloc_uint64_t size
     
    hwloc_uint64_t count
     
    -

    Detailed Description

    -

    Array of local memory page types, NULL if no local memory and page_types is 0.

    -

    The array is sorted by increasing size fields. It contains page_types_len slots.

    -

    Field Documentation

    - -

    ◆ count

    - -
    -
    - - - - -
    hwloc_uint64_t hwloc_obj_attr_u::hwloc_numanode_attr_s::hwloc_memory_page_type_s::count
    -
    - -

    Number of pages of this size.

    - -
    -
    - -

    ◆ size

    - -
    -
    - - - - -
    hwloc_uint64_t hwloc_obj_attr_u::hwloc_numanode_attr_s::hwloc_memory_page_type_s::size
    -
    - -

    Size of pages.

    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - - -
    -
    -Data Fields
    -
    -
    hwloc_obj_attr_u::hwloc_cache_attr_s Struct Reference
    -
    -
    - -

    #include <hwloc.h>

    - - - - - - - - - - - - -

    -Data Fields

    hwloc_uint64_t size
     
    unsigned depth
     
    unsigned linesize
     
    int associativity
     
    hwloc_obj_cache_type_t type
     
    -

    Detailed Description

    -

    Cache-specific Object Attributes.

    -

    Field Documentation

    - -

    ◆ associativity

    - -
    -
    - - - - -
    int hwloc_obj_attr_u::hwloc_cache_attr_s::associativity
    -
    - -

    Ways of associativity, -1 if fully associative, 0 if unknown.

    - -
    -
    - -

    ◆ depth

    - -
    -
    - - - - -
    unsigned hwloc_obj_attr_u::hwloc_cache_attr_s::depth
    -
    - -

    Depth of cache (e.g., L1, L2, ...etc.)

    - -
    -
    - -

    ◆ linesize

    - -
    -
    - - - - -
    unsigned hwloc_obj_attr_u::hwloc_cache_attr_s::linesize
    -
    - -

    Cache-line size in bytes. 0 if unknown.

    - -
    -
    - -

    ◆ size

    - -
    -
    - - - - -
    hwloc_uint64_t hwloc_obj_attr_u::hwloc_cache_attr_s::size
    -
    - -

    Size of cache in bytes.

    - -
    -
    - -

    ◆ type

    - -
    -
    - - - - -
    hwloc_obj_cache_type_t hwloc_obj_attr_u::hwloc_cache_attr_s::type
    -
    - -

    Cache type.

    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - - -
    -
    -Data Fields
    -
    -
    hwloc_obj_attr_u::hwloc_group_attr_s Struct Reference
    -
    -
    - -

    #include <hwloc.h>

    - - - - - - - - - - -

    -Data Fields

    unsigned depth
     
    unsigned kind
     
    unsigned subkind
     
    unsigned char dont_merge
     
    -

    Detailed Description

    -

    Group-specific Object Attributes.

    -

    Field Documentation

    - -

    ◆ depth

    - -
    -
    - - - - -
    unsigned hwloc_obj_attr_u::hwloc_group_attr_s::depth
    -
    - -

    Depth of group object. It may change if intermediate Group objects are added.

    - -
    -
    - -

    ◆ dont_merge

    - -
    -
    - - - - -
    unsigned char hwloc_obj_attr_u::hwloc_group_attr_s::dont_merge
    -
    - -

    Flag preventing groups from being automatically merged with identical parent or children.

    - -
    -
    - -

    ◆ kind

    - -
    -
    - - - - -
    unsigned hwloc_obj_attr_u::hwloc_group_attr_s::kind
    -
    - -

    Internally-used kind of group.

    - -
    -
    - -

    ◆ subkind

    - -
    -
    - - - - -
    unsigned hwloc_obj_attr_u::hwloc_group_attr_s::subkind
    -
    - -

    Internally-used subkind to distinguish different levels of groups with same kind.

    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - - -
    -
    -Data Fields
    -
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s Struct Reference
    -
    -
    - -

    #include <hwloc.h>

    - - - - - - - - - - - - - - - - - - - - - - - - -

    -Data Fields

    unsigned short domain
     
    unsigned char bus
     
    unsigned char dev
     
    unsigned char func
     
    unsigned short class_id
     
    unsigned short vendor_id
     
    unsigned short device_id
     
    unsigned short subvendor_id
     
    unsigned short subdevice_id
     
    unsigned char revision
     
    float linkspeed
     
    -

    Detailed Description

    -

    PCI Device specific Object Attributes.

    -

    Field Documentation

    - -

    ◆ bus

    - -
    -
    - - - - -
    unsigned char hwloc_obj_attr_u::hwloc_pcidev_attr_s::bus
    -
    - -
    -
    - -

    ◆ class_id

    - -
    -
    - - - - -
    unsigned short hwloc_obj_attr_u::hwloc_pcidev_attr_s::class_id
    -
    - -
    -
    - -

    ◆ dev

    - -
    -
    - - - - -
    unsigned char hwloc_obj_attr_u::hwloc_pcidev_attr_s::dev
    -
    - -
    -
    - -

    ◆ device_id

    - -
    -
    - - - - -
    unsigned short hwloc_obj_attr_u::hwloc_pcidev_attr_s::device_id
    -
    - -
    -
    - -

    ◆ domain

    - -
    -
    - - - - -
    unsigned short hwloc_obj_attr_u::hwloc_pcidev_attr_s::domain
    -
    - -
    -
    - -

    ◆ func

    - -
    -
    - - - - -
    unsigned char hwloc_obj_attr_u::hwloc_pcidev_attr_s::func
    -
    - -
    -
    - -

    ◆ linkspeed

    - -
    -
    - - - - -
    float hwloc_obj_attr_u::hwloc_pcidev_attr_s::linkspeed
    -
    - -
    -
    - -

    ◆ revision

    - -
    -
    - - - - -
    unsigned char hwloc_obj_attr_u::hwloc_pcidev_attr_s::revision
    -
    - -
    -
    - -

    ◆ subdevice_id

    - -
    -
    - - - - -
    unsigned short hwloc_obj_attr_u::hwloc_pcidev_attr_s::subdevice_id
    -
    - -
    -
    - -

    ◆ subvendor_id

    - -
    -
    - - - - -
    unsigned short hwloc_obj_attr_u::hwloc_pcidev_attr_s::subvendor_id
    -
    - -
    -
    - -

    ◆ vendor_id

    - -
    -
    - - - - -
    unsigned short hwloc_obj_attr_u::hwloc_pcidev_attr_s::vendor_id
    -
    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - - -
    -
    -Data Fields
    -
    -
    hwloc_obj_attr_u::hwloc_bridge_attr_s Struct Reference
    -
    -
    - -

    #include <hwloc.h>

    - - - - - - - - - - - - - - - - - - - - - - - - - -

    -Data Fields

    union {
       struct hwloc_pcidev_attr_s   pci
     
    } upstream
     
    hwloc_obj_bridge_type_t upstream_type
     
    union {
       struct {
          unsigned short   domain
     
          unsigned char   secondary_bus
     
          unsigned char   subordinate_bus
     
       }   pci
     
    } downstream
     
    hwloc_obj_bridge_type_t downstream_type
     
    unsigned depth
     
    -

    Detailed Description

    -

    Bridge specific Object Attributes.

    -

    Field Documentation

    - -

    ◆ depth

    - -
    -
    - - - - -
    unsigned hwloc_obj_attr_u::hwloc_bridge_attr_s::depth
    -
    - -
    -
    - -

    ◆ domain

    - -
    -
    - - - - -
    unsigned short hwloc_obj_attr_u::hwloc_bridge_attr_s::domain
    -
    - -
    -
    - -

    ◆ 

    - -
    -
    - - - - -
    union { ... } hwloc_obj_attr_u::hwloc_bridge_attr_s::downstream
    -
    - -
    -
    - -

    ◆ downstream_type

    - -
    -
    - - - - -
    hwloc_obj_bridge_type_t hwloc_obj_attr_u::hwloc_bridge_attr_s::downstream_type
    -
    - -
    -
    - -

    ◆  [1/2]

    - -
    -
    - - - - -
    struct { ... } hwloc_obj_attr_u::hwloc_bridge_attr_s::pci
    -
    - -
    -
    - -

    ◆ pci [2/2]

    - -
    -
    - - - - -
    struct hwloc_pcidev_attr_s hwloc_obj_attr_u::hwloc_bridge_attr_s::pci
    -
    - -
    -
    - -

    ◆ secondary_bus

    - -
    -
    - - - - -
    unsigned char hwloc_obj_attr_u::hwloc_bridge_attr_s::secondary_bus
    -
    - -
    -
    - -

    ◆ subordinate_bus

    - -
    -
    - - - - -
    unsigned char hwloc_obj_attr_u::hwloc_bridge_attr_s::subordinate_bus
    -
    - -
    -
    - -

    ◆ 

    - -
    -
    - - - - -
    union { ... } hwloc_obj_attr_u::hwloc_bridge_attr_s::upstream
    -
    - -
    -
    - -

    ◆ upstream_type

    - -
    -
    - - - - -
    hwloc_obj_bridge_type_t hwloc_obj_attr_u::hwloc_bridge_attr_s::upstream_type
    -
    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - - -
    -
    -Data Fields
    -
    -
    hwloc_obj_attr_u::hwloc_osdev_attr_s Struct Reference
    -
    -
    - -

    #include <hwloc.h>

    - - - - -

    -Data Fields

    hwloc_obj_osdev_type_t type
     
    -

    Detailed Description

    -

    OS Device specific Object Attributes.

    -

    Field Documentation

    - -

    ◆ type

    - -
    -
    - - - - -
    hwloc_obj_osdev_type_t hwloc_obj_attr_u::hwloc_osdev_attr_s::type
    -
    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - -
    -
    -Data Fields
    -
    -
    hwloc_info_s Struct Reference
    Object Structure and Attributes
    -
    -
    - -

    #include <hwloc.h>

    - - - - - - -

    -Data Fields

    char * name
     
    char * value
     
    -

    Detailed Description

    -

    Object info.

    -
    See also
    Consulting and Adding Key-Value Info Attributes
    -

    Field Documentation

    - -

    ◆ name

    - -
    -
    - - - - -
    char* hwloc_info_s::name
    -
    - -

    Info name.

    - -
    -
    - -

    ◆ value

    - -
    -
    - - - - -
    char* hwloc_info_s::value
    -
    - -

    Info value.

    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - -
    -
    -Data Fields
    -
    -
    hwloc_topology_discovery_support Struct Reference
    Topology Detection Configuration and Query
    -
    -
    - -

    #include <hwloc.h>

    - - - - - - - - - - - - - - -

    -Data Fields

    unsigned char pu
     
    unsigned char numa
     
    unsigned char numa_memory
     
    unsigned char disallowed_pu
     
    unsigned char disallowed_numa
     
    unsigned char cpukind_efficiency
     
    -

    Detailed Description

    -

    Flags describing actual discovery support for this topology.

    -

    Field Documentation

    - -

    ◆ cpukind_efficiency

    - -
    -
    - - - - -
    unsigned char hwloc_topology_discovery_support::cpukind_efficiency
    -
    - -

    Detecting the efficiency of CPU kinds is supported, see Kinds of CPU cores.

    - -
    -
    - -

    ◆ disallowed_numa

    - -
    -
    - - - - -
    unsigned char hwloc_topology_discovery_support::disallowed_numa
    -
    - -

    Detecting and identifying NUMA nodes that are not available to the current process is supported.

    - -
    -
    - -

    ◆ disallowed_pu

    - -
    -
    - - - - -
    unsigned char hwloc_topology_discovery_support::disallowed_pu
    -
    - -

    Detecting and identifying PU objects that are not available to the current process is supported.

    - -
    -
    - -

    ◆ numa

    - -
    -
    - - - - -
    unsigned char hwloc_topology_discovery_support::numa
    -
    - -

    Detecting the number of NUMA nodes is supported.

    - -
    -
    - -

    ◆ numa_memory

    - -
    -
    - - - - -
    unsigned char hwloc_topology_discovery_support::numa_memory
    -
    - -

    Detecting the amount of memory in NUMA nodes is supported.

    - -
    -
    - -

    ◆ pu

    - -
    -
    - - - - -
    unsigned char hwloc_topology_discovery_support::pu
    -
    - -

    Detecting the number of PU objects is supported.

    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - -
    -
    -Data Fields
    -
    -
    hwloc_topology_cpubind_support Struct Reference
    Topology Detection Configuration and Query
    -
    -
    - -

    #include <hwloc.h>

    - - - - - - - - - - - - - - - - - - - - - - - - -

    -Data Fields

    unsigned char set_thisproc_cpubind
     
    unsigned char get_thisproc_cpubind
     
    unsigned char set_proc_cpubind
     
    unsigned char get_proc_cpubind
     
    unsigned char set_thisthread_cpubind
     
    unsigned char get_thisthread_cpubind
     
    unsigned char set_thread_cpubind
     
    unsigned char get_thread_cpubind
     
    unsigned char get_thisproc_last_cpu_location
     
    unsigned char get_proc_last_cpu_location
     
    unsigned char get_thisthread_last_cpu_location
     
    -

    Detailed Description

    -

    Flags describing actual PU binding support for this topology.

    -

    A flag may be set even if the feature isn't supported in all cases (e.g. binding to random sets of non-contiguous objects).

    -

    Field Documentation

    - -

    ◆ get_proc_cpubind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_cpubind_support::get_proc_cpubind
    -
    -

    Getting the binding of a whole given process is supported.

    - -
    -
    - -

    ◆ get_proc_last_cpu_location

    - -
    -
    - - - - -
    unsigned char hwloc_topology_cpubind_support::get_proc_last_cpu_location
    -
    -

    Getting the last processors where a whole process ran is supported

    - -
    -
    - -

    ◆ get_thisproc_cpubind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_cpubind_support::get_thisproc_cpubind
    -
    -

    Getting the binding of the whole current process is supported.

    - -
    -
    - -

    ◆ get_thisproc_last_cpu_location

    - -
    -
    - - - - -
    unsigned char hwloc_topology_cpubind_support::get_thisproc_last_cpu_location
    -
    -

    Getting the last processors where the whole current process ran is supported

    - -
    -
    - -

    ◆ get_thisthread_cpubind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_cpubind_support::get_thisthread_cpubind
    -
    -

    Getting the binding of the current thread only is supported.

    - -
    -
    - -

    ◆ get_thisthread_last_cpu_location

    - -
    -
    - - - - -
    unsigned char hwloc_topology_cpubind_support::get_thisthread_last_cpu_location
    -
    -

    Getting the last processors where the current thread ran is supported

    - -
    -
    - -

    ◆ get_thread_cpubind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_cpubind_support::get_thread_cpubind
    -
    -

    Getting the binding of a given thread only is supported.

    - -
    -
    - -

    ◆ set_proc_cpubind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_cpubind_support::set_proc_cpubind
    -
    -

    Binding a whole given process is supported.

    - -
    -
    - -

    ◆ set_thisproc_cpubind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_cpubind_support::set_thisproc_cpubind
    -
    -

    Binding the whole current process is supported.

    - -
    -
    - -

    ◆ set_thisthread_cpubind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_cpubind_support::set_thisthread_cpubind
    -
    -

    Binding the current thread only is supported.

    - -
    -
    - -

    ◆ set_thread_cpubind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_cpubind_support::set_thread_cpubind
    -
    -

    Binding a given thread only is supported.

    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - -
    -
    -Data Fields
    -
    -
    hwloc_topology_membind_support Struct Reference
    Topology Detection Configuration and Query
    -
    -
    - -

    #include <hwloc.h>

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

    -Data Fields

    unsigned char set_thisproc_membind
     
    unsigned char get_thisproc_membind
     
    unsigned char set_proc_membind
     
    unsigned char get_proc_membind
     
    unsigned char set_thisthread_membind
     
    unsigned char get_thisthread_membind
     
    unsigned char set_area_membind
     
    unsigned char get_area_membind
     
    unsigned char alloc_membind
     
    unsigned char firsttouch_membind
     
    unsigned char bind_membind
     
    unsigned char interleave_membind
     
    unsigned char nexttouch_membind
     
    unsigned char migrate_membind
     
    unsigned char get_area_memlocation
     
    -

    Detailed Description

    -

    Flags describing actual memory binding support for this topology.

    -

    A flag may be set even if the feature isn't supported in all cases (e.g. binding to random sets of non-contiguous objects).

    -

    Field Documentation

    - -

    ◆ alloc_membind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_membind_support::alloc_membind
    -
    -

    Allocating a bound memory area is supported.

    - -
    -
    - -

    ◆ bind_membind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_membind_support::bind_membind
    -
    -

    Bind policy is supported.

    - -
    -
    - -

    ◆ firsttouch_membind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_membind_support::firsttouch_membind
    -
    -

    First-touch policy is supported.

    - -
    -
    - -

    ◆ get_area_membind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_membind_support::get_area_membind
    -
    -

    Getting the binding of a given memory area is supported.

    - -
    -
    - -

    ◆ get_area_memlocation

    - -
    -
    - - - - -
    unsigned char hwloc_topology_membind_support::get_area_memlocation
    -
    -

    Getting the last NUMA nodes where a memory area was allocated is supported

    - -
    -
    - -

    ◆ get_proc_membind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_membind_support::get_proc_membind
    -
    -

    Getting the binding of a whole given process is supported.

    - -
    -
    - -

    ◆ get_thisproc_membind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_membind_support::get_thisproc_membind
    -
    -

    Getting the binding of the whole current process is supported.

    - -
    -
    - -

    ◆ get_thisthread_membind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_membind_support::get_thisthread_membind
    -
    -

    Getting the binding of the current thread only is supported.

    - -
    -
    - -

    ◆ interleave_membind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_membind_support::interleave_membind
    -
    -

    Interleave policy is supported.

    - -
    -
    - -

    ◆ migrate_membind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_membind_support::migrate_membind
    -
    -

    Migration flags is supported.

    - -
    -
    - -

    ◆ nexttouch_membind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_membind_support::nexttouch_membind
    -
    -

    Next-touch migration policy is supported.

    - -
    -
    - -

    ◆ set_area_membind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_membind_support::set_area_membind
    -
    -

    Binding a given memory area is supported.

    - -
    -
    - -

    ◆ set_proc_membind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_membind_support::set_proc_membind
    -
    -

    Binding a whole given process is supported.

    - -
    -
    - -

    ◆ set_thisproc_membind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_membind_support::set_thisproc_membind
    -
    -

    Binding the whole current process is supported.

    - -
    -
    - -

    ◆ set_thisthread_membind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_membind_support::set_thisthread_membind
    -
    -

    Binding the current thread only is supported.

    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - -
    -
    -Data Fields
    -
    -
    hwloc_topology_misc_support Struct Reference
    Topology Detection Configuration and Query
    -
    -
    - -

    #include <hwloc.h>

    - - - - -

    -Data Fields

    unsigned char imported_support
     
    -

    Detailed Description

    -

    Flags describing miscellaneous features.

    -

    Field Documentation

    - -

    ◆ imported_support

    - -
    -
    - - - - -
    unsigned char hwloc_topology_misc_support::imported_support
    -
    -

    Support was imported when importing another topology, see HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT.

    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - -
    -
    -Data Fields
    -
    -
    hwloc_topology_support Struct Reference
    Topology Detection Configuration and Query
    -
    -
    - -

    #include <hwloc.h>

    - - - - - - - - - - -

    -Data Fields

    struct hwloc_topology_discovery_support * discovery
     
    struct hwloc_topology_cpubind_support * cpubind
     
    struct hwloc_topology_membind_support * membind
     
    struct hwloc_topology_misc_support * misc
     
    -

    Detailed Description

    -

    Set of flags describing actual support for this topology.

    -

    This is retrieved with hwloc_topology_get_support() and will be valid until the topology object is destroyed. Note: the values are correct only after discovery.

    -

    Field Documentation

    - -

    ◆ cpubind

    - -
    -
    - - - - -
    struct hwloc_topology_cpubind_support* hwloc_topology_support::cpubind
    -
    - -
    -
    - -

    ◆ discovery

    - -
    -
    - - - - -
    struct hwloc_topology_discovery_support* hwloc_topology_support::discovery
    -
    - -
    -
    - -

    ◆ membind

    - -
    -
    - - - - -
    struct hwloc_topology_membind_support* hwloc_topology_support::membind
    -
    - -
    -
    - -

    ◆ misc

    - -
    -
    - - - - -
    struct hwloc_topology_misc_support* hwloc_topology_support::misc
    -
    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - -
    -
    -Data Fields
    -
    -
    hwloc_distances_s Struct Reference
    Retrieve distances between objects
    -
    -
    - -

    #include <distances.h>

    - - - - - - - - - - -

    -Data Fields

    unsigned nbobjs
     
    hwloc_obj_t * objs
     
    unsigned long kind
     
    hwloc_uint64_t * values
     
    -

    Detailed Description

    -

    Matrix of distances between a set of objects.

    -

    This matrix often contains latencies between NUMA nodes (as reported in the System Locality Distance Information Table (SLIT) in the ACPI specification), which may or may not be physically accurate. It corresponds to the latency for accessing the memory of one node from a core in another node. The corresponding kind is HWLOC_DISTANCES_KIND_FROM_OS | HWLOC_DISTANCES_KIND_FROM_USER. The name of this distances structure is "NUMALatency". Others distance structures include and "XGMIBandwidth", "XGMIHops", "XeLinkBandwidth" and "NVLinkBandwidth".

    -

    The matrix may also contain bandwidths between random sets of objects, possibly provided by the user, as specified in the kind attribute.

    -

    Pointers objs and values should not be replaced, reallocated, freed, etc. However callers are allowed to modify kind as well as the contents of objs and values arrays. For instance, if there is a single NUMA node per Package, hwloc_get_obj_with_same_locality() may be used to convert between them and replace NUMA nodes in the objs array with the corresponding Packages. See also hwloc_distances_transform() for applying some transformations to the structure.

    -

    Field Documentation

    - -

    ◆ kind

    - -
    -
    - - - - -
    unsigned long hwloc_distances_s::kind
    -
    - -

    OR'ed set of hwloc_distances_kind_e.

    - -
    -
    - -

    ◆ nbobjs

    - -
    -
    - - - - -
    unsigned hwloc_distances_s::nbobjs
    -
    - -

    Number of objects described by the distance matrix.

    - -
    -
    - -

    ◆ objs

    - -
    -
    - - - - -
    hwloc_obj_t* hwloc_distances_s::objs
    -
    - -

    Array of objects described by the distance matrix. These objects are not in any particular order, see hwloc_distances_obj_index() and hwloc_distances_obj_pair_values() for easy ways to find objects in this array and their corresponding values.

    - -
    -
    - -

    ◆ values

    - -
    -
    - - - - -
    hwloc_uint64_t* hwloc_distances_s::values
    -
    - -

    Matrix of distances between objects, stored as a one-dimension array.

    -

    Distance from i-th to j-th object is stored in slot i*nbobjs+j. The meaning of the value depends on the kind attribute.

    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - -
    -
    -Data Structures | -Data Fields
    -
    -
    hwloc_location Struct Reference
    Comparing memory node attributes for finding where to allocate on
    -
    -
    - -

    #include <memattrs.h>

    - - - - -

    -Data Structures

    union  hwloc_location_u
     
    - - - - - -

    -Data Fields

    enum hwloc_location_type_e type
     
    union hwloc_location::hwloc_location_u location
     
    -

    Detailed Description

    -

    Where to measure attributes from.

    -

    Field Documentation

    - -

    ◆ location

    - -
    -
    - - - - -
    union hwloc_location::hwloc_location_u hwloc_location::location
    -
    - -
    -
    - -

    ◆ type

    - -
    -
    - - - - -
    enum hwloc_location_type_e hwloc_location::type
    -
    - -

    Type of location.

    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - - -
    -
    -Data Fields
    -
    -
    hwloc_location::hwloc_location_u Union Reference
    -
    -
    - -

    #include <memattrs.h>

    - - - - - - -

    -Data Fields

    hwloc_cpuset_t cpuset
     
    hwloc_obj_t object
     
    -

    Detailed Description

    -

    Actual location.

    -

    Field Documentation

    - -

    ◆ cpuset

    - -
    -
    - - - - -
    hwloc_cpuset_t hwloc_location::hwloc_location_u::cpuset
    -
    - -

    Location as a cpuset, when the location type is HWLOC_LOCATION_TYPE_CPUSET.

    - -
    -
    - -

    ◆ object

    - -
    -
    - - - - -
    hwloc_obj_t hwloc_location::hwloc_location_u::object
    -
    - -

    Location as an object, when the location type is HWLOC_LOCATION_TYPE_OBJECT.

    - -
    -
    -
    The documentation for this union was generated from the following file: -
    - - - - - - - -
    -
    -Data Fields
    -
    -
    hwloc_cl_device_topology_amd Union Reference
    -
    -
    - -

    #include <opencl.h>

    - - - - - - - - - - - - - - - - - - - - - - -

    -Data Fields

    struct {
       cl_uint   type
     
       cl_uint   data [5]
     
    } raw
     
    struct {
       cl_uint   type
     
       cl_char   unused [17]
     
       cl_char   bus
     
       cl_char   device
     
       cl_char   function
     
    } pcie
     
    -

    Field Documentation

    - -

    ◆ bus

    - -
    -
    - - - - -
    cl_char hwloc_cl_device_topology_amd::bus
    -
    - -
    -
    - -

    ◆ data

    - -
    -
    - - - - -
    cl_uint hwloc_cl_device_topology_amd::data[5]
    -
    - -
    -
    - -

    ◆ device

    - -
    -
    - - - - -
    cl_char hwloc_cl_device_topology_amd::device
    -
    - -
    -
    - -

    ◆ function

    - -
    -
    - - - - -
    cl_char hwloc_cl_device_topology_amd::function
    -
    - -
    -
    - -

    ◆ 

    - -
    -
    - - - - -
    struct { ... } hwloc_cl_device_topology_amd::pcie
    -
    - -
    -
    - -

    ◆ 

    - -
    -
    - - - - -
    struct { ... } hwloc_cl_device_topology_amd::raw
    -
    - -
    -
    - -

    ◆ type

    - -
    -
    - - - - -
    cl_uint hwloc_cl_device_topology_amd::type
    -
    - -
    -
    - -

    ◆ unused

    - -
    -
    - - - - -
    cl_char hwloc_cl_device_topology_amd::unused[17]
    -
    - -
    -
    -
    The documentation for this union was generated from the following file: -
    - - - - - - - -
    -
    -Data Structures | -Data Fields
    -
    -
    hwloc_topology_diff_obj_attr_u Union Reference
    Topology differences
    -
    -
    - -

    #include <diff.h>

    - - - - - - - - -

    -Data Structures

    struct  hwloc_topology_diff_obj_attr_generic_s
     
    struct  hwloc_topology_diff_obj_attr_string_s
     
    struct  hwloc_topology_diff_obj_attr_uint64_s
     
    - - - - - - - -

    -Data Fields

    struct hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_generic_s generic
     
    struct hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s uint64
     
    struct hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s string
     
    -

    Detailed Description

    -

    One object attribute difference.

    -

    Field Documentation

    - -

    ◆ generic

    - -
    -
    - - - - -
    struct hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_generic_s hwloc_topology_diff_obj_attr_u::generic
    -
    - -
    -
    - -

    ◆ string

    - -
    -
    - - - - -
    struct hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s hwloc_topology_diff_obj_attr_u::string
    -
    - -
    -
    - -

    ◆ uint64

    - -
    -
    - - - - -
    struct hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s hwloc_topology_diff_obj_attr_u::uint64
    -
    - -
    -
    -
    The documentation for this union was generated from the following file: -
    - - - - - - - - -
    -
    -Data Fields
    -
    -
    hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_generic_s Struct Reference
    -
    -
    - -

    #include <diff.h>

    - - - - -

    -Data Fields

    hwloc_topology_diff_obj_attr_type_t type
     
    -

    Field Documentation

    - -

    ◆ type

    - -
    -
    - - - - -
    hwloc_topology_diff_obj_attr_type_t hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_generic_s::type
    -
    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - - -
    -
    -Data Fields
    -
    -
    hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s Struct Reference
    -
    -
    - -

    #include <diff.h>

    - - - - - - - - - - -

    -Data Fields

    hwloc_topology_diff_obj_attr_type_t type
     
    hwloc_uint64_t index
     
    hwloc_uint64_t oldvalue
     
    hwloc_uint64_t newvalue
     
    -

    Detailed Description

    -

    Integer attribute modification with an optional index.

    -

    Field Documentation

    - -

    ◆ index

    - -
    -
    - - - - -
    hwloc_uint64_t hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s::index
    -
    - -
    -
    - -

    ◆ newvalue

    - -
    -
    - - - - -
    hwloc_uint64_t hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s::newvalue
    -
    - -
    -
    - -

    ◆ oldvalue

    - -
    -
    - - - - -
    hwloc_uint64_t hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s::oldvalue
    -
    - -
    -
    - -

    ◆ type

    - -
    -
    - - - - -
    hwloc_topology_diff_obj_attr_type_t hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s::type
    -
    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - - -
    -
    -Data Fields
    -
    -
    hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s Struct Reference
    -
    -
    - -

    #include <diff.h>

    - - - - - - - - - - -

    -Data Fields

    hwloc_topology_diff_obj_attr_type_t type
     
    char * name
     
    char * oldvalue
     
    char * newvalue
     
    -

    Detailed Description

    -

    String attribute modification with an optional name.

    -

    Field Documentation

    - -

    ◆ name

    - -
    -
    - - - - -
    char* hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s::name
    -
    - -
    -
    - -

    ◆ newvalue

    - -
    -
    - - - - -
    char* hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s::newvalue
    -
    - -
    -
    - -

    ◆ oldvalue

    - -
    -
    - - - - -
    char* hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s::oldvalue
    -
    - -
    -
    - -

    ◆ type

    - -
    -
    - - - - -
    hwloc_topology_diff_obj_attr_type_t hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s::type
    -
    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - -
    -
    -Data Structures | -Data Fields
    -
    -
    hwloc_topology_diff_u Union Reference
    Topology differences
    -
    -
    - -

    #include <diff.h>

    - - - - - - - - -

    -Data Structures

    struct  hwloc_topology_diff_generic_s
     
    struct  hwloc_topology_diff_obj_attr_s
     
    struct  hwloc_topology_diff_too_complex_s
     
    - - - - - - - -

    -Data Fields

    struct hwloc_topology_diff_u::hwloc_topology_diff_generic_s generic
     
    struct hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s obj_attr
     
    struct hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s too_complex
     
    -

    Detailed Description

    -

    One element of a difference list between two topologies.

    -

    Field Documentation

    - -

    ◆ generic

    - -
    -
    - - - - -
    struct hwloc_topology_diff_u::hwloc_topology_diff_generic_s hwloc_topology_diff_u::generic
    -
    - -
    -
    - -

    ◆ obj_attr

    - -
    -
    - - - - -
    struct hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s hwloc_topology_diff_u::obj_attr
    -
    - -
    -
    - -

    ◆ too_complex

    - -
    -
    - - - - -
    struct hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s hwloc_topology_diff_u::too_complex
    -
    - -
    -
    -
    The documentation for this union was generated from the following file: -
    - - - - - - - - -
    -
    -Data Fields
    -
    -
    hwloc_topology_diff_u::hwloc_topology_diff_generic_s Struct Reference
    -
    -
    - -

    #include <diff.h>

    - - - - - - -

    -Data Fields

    hwloc_topology_diff_type_t type
     
    union hwloc_topology_diff_u * next
     
    -

    Field Documentation

    - -

    ◆ next

    - -
    -
    - - - - -
    union hwloc_topology_diff_u* hwloc_topology_diff_u::hwloc_topology_diff_generic_s::next
    -
    - -
    -
    - -

    ◆ type

    - -
    -
    - - - - -
    hwloc_topology_diff_type_t hwloc_topology_diff_u::hwloc_topology_diff_generic_s::type
    -
    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - - -
    -
    -Data Fields
    -
    -
    hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s Struct Reference
    -
    -
    - -

    #include <diff.h>

    - - - - - - - - - - - - -

    -Data Fields

    hwloc_topology_diff_type_t type
     
    union hwloc_topology_diff_u * next
     
    int obj_depth
     
    unsigned obj_index
     
    union hwloc_topology_diff_obj_attr_u diff
     
    -

    Field Documentation

    - -

    ◆ diff

    - -
    -
    - - - - -
    union hwloc_topology_diff_obj_attr_u hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s::diff
    -
    - -
    -
    - -

    ◆ next

    - -
    -
    - - - - -
    union hwloc_topology_diff_u* hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s::next
    -
    - -
    -
    - -

    ◆ obj_depth

    - -
    -
    - - - - -
    int hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s::obj_depth
    -
    - -
    -
    - -

    ◆ obj_index

    - -
    -
    - - - - -
    unsigned hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s::obj_index
    -
    - -
    -
    - -

    ◆ type

    - -
    -
    - - - - -
    hwloc_topology_diff_type_t hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s::type
    -
    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - - -
    -
    -Data Fields
    -
    -
    hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s Struct Reference
    -
    -
    - -

    #include <diff.h>

    - - - - - - - - - - -

    -Data Fields

    hwloc_topology_diff_type_t type
     
    union hwloc_topology_diff_u * next
     
    int obj_depth
     
    unsigned obj_index
     
    -

    Field Documentation

    - -

    ◆ next

    - -
    -
    - - - - -
    union hwloc_topology_diff_u* hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s::next
    -
    - -
    -
    - -

    ◆ obj_depth

    - -
    -
    - - - - -
    int hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s::obj_depth
    -
    - -
    -
    - -

    ◆ obj_index

    - -
    -
    - - - - -
    unsigned hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s::obj_index
    -
    - -
    -
    - -

    ◆ type

    - -
    -
    - - - - -
    hwloc_topology_diff_type_t hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s::type
    -
    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - -
    -
    -Data Fields
    -
    -
    hwloc_disc_component Struct Reference
    Components and Plugins: Discovery components
    -
    -
    - -

    #include <plugins.h>

    - - - - - - - - - - - - - - -

    -Data Fields

    const char * name
     
    unsigned phases
     
    unsigned excluded_phases
     
    struct hwloc_backend *(* instantiate )(struct hwloc_topology *topology, struct hwloc_disc_component *component, unsigned excluded_phases, const void *data1, const void *data2, const void *data3)
     
    unsigned priority
     
    unsigned enabled_by_default
     
    -

    Detailed Description

    -

    Discovery component structure.

    -

    This is the major kind of components, taking care of the discovery. They are registered by generic components, either statically-built or as plugins.

    -

    Field Documentation

    - -

    ◆ enabled_by_default

    - -
    -
    - - - - -
    unsigned hwloc_disc_component::enabled_by_default
    -
    - -

    Enabled by default. If unset, if will be disabled unless explicitly requested.

    - -
    -
    - -

    ◆ excluded_phases

    - -
    -
    - - - - -
    unsigned hwloc_disc_component::excluded_phases
    -
    - -

    Component phases to exclude, as an OR'ed set of hwloc_disc_phase_t.

    -

    For a GLOBAL component, this usually includes all other phases (~UL).

    -

    Other components only exclude types that may bring conflicting topology information. MISC components should likely not be excluded since they usually bring non-primary additional information.

    - -
    -
    - -

    ◆ instantiate

    - -
    -
    - - - - -
    struct hwloc_backend*(* hwloc_disc_component::instantiate) (struct hwloc_topology *topology, struct hwloc_disc_component *component, unsigned excluded_phases, const void *data1, const void *data2, const void *data3)
    -
    - -

    Instantiate callback to create a backend from the component. Parameters data1, data2, data3 are NULL except for components that have special enabling routines such as hwloc_topology_set_xml().

    - -
    -
    - -

    ◆ name

    - -
    -
    - - - - -
    const char* hwloc_disc_component::name
    -
    - -

    Name. If this component is built as a plugin, this name does not have to match the plugin filename.

    - -
    -
    - -

    ◆ phases

    - -
    -
    - - - - -
    unsigned hwloc_disc_component::phases
    -
    - -

    Discovery phases performed by this component. OR'ed set of hwloc_disc_phase_t.

    - -
    -
    - -

    ◆ priority

    - -
    -
    - - - - -
    unsigned hwloc_disc_component::priority
    -
    - -

    Component priority. Used to sort topology->components, higher priority first. Also used to decide between two components with the same name.

    -

    Usual values are 50 for native OS (or platform) components, 45 for x86, 40 for no-OS fallback, 30 for global components (xml, synthetic), 20 for pci, 10 for other misc components (opencl etc.).

    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - -
    -
    -Data Fields
    -
    -
    hwloc_disc_status Struct Reference
    Components and Plugins: Discovery backends
    -
    -
    - -

    #include <plugins.h>

    - - - - - - - - -

    -Data Fields

    hwloc_disc_phase_t phase
     
    unsigned excluded_phases
     
    unsigned long flags
     
    -

    Detailed Description

    -

    Discovery status structure.

    -

    Used by the core and backends to inform about what has been/is being done during the discovery process.

    -

    Field Documentation

    - -

    ◆ excluded_phases

    - -
    -
    - - - - -
    unsigned hwloc_disc_status::excluded_phases
    -
    - -

    Dynamically excluded phases. If a component decides during discovery that some phases are no longer needed.

    - -
    -
    - -

    ◆ flags

    - -
    -
    - - - - -
    unsigned long hwloc_disc_status::flags
    -
    - -

    OR'ed set of hwloc_disc_status_flag_e.

    - -
    -
    - -

    ◆ phase

    - -
    -
    - - - - -
    hwloc_disc_phase_t hwloc_disc_status::phase
    -
    - -

    The current discovery phase that is performed. Must match one of the phases in the component phases field.

    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - -
    -
    -Data Fields
    -
    -
    hwloc_backend Struct Reference
    Components and Plugins: Discovery backends
    -
    -
    - -

    #include <plugins.h>

    - - - - - - - - - - - - - - - - -

    -Data Fields

    unsigned phases
     
    unsigned long flags
     
    int is_thissystem
     
    void * private_data
     
    void(* disable )(struct hwloc_backend *backend)
     
    int(* discover )(struct hwloc_backend *backend, struct hwloc_disc_status *status)
     
    int(* get_pci_busid_cpuset )(struct hwloc_backend *backend, struct hwloc_pcidev_attr_s *busid, hwloc_bitmap_t cpuset)
     
    -

    Detailed Description

    -

    Discovery backend structure.

    -

    A backend is the instantiation of a discovery component. When a component gets enabled for a topology, its instantiate() callback creates a backend.

    -

    hwloc_backend_alloc() initializes all fields to default values that the component may change (except "component" and "next") before enabling the backend with hwloc_backend_enable().

    -

    Most backends assume that the topology is_thissystem flag is set because they talk to the underlying operating system. However they may still be used in topologies without the is_thissystem flag for debugging reasons. In practice, they are usually auto-disabled in such cases (excluded by xml or synthetic backends, or by environment variables when changing the Linux fsroot or the x86 cpuid path).

    -

    Field Documentation

    - -

    ◆ disable

    - -
    -
    - - - - -
    void(* hwloc_backend::disable) (struct hwloc_backend *backend)
    -
    - -

    Callback for freeing the private_data. May be NULL.

    - -
    -
    - -

    ◆ discover

    - -
    -
    - - - - -
    int(* hwloc_backend::discover) (struct hwloc_backend *backend, struct hwloc_disc_status *status)
    -
    - -

    Main discovery callback. returns -1 on error, either because it couldn't add its objects ot the existing topology, or because of an actual discovery/gathering failure. May be NULL.

    - -
    -
    - -

    ◆ flags

    - -
    -
    - - - - -
    unsigned long hwloc_backend::flags
    -
    - -

    Backend flags, currently always 0.

    - -
    -
    - -

    ◆ get_pci_busid_cpuset

    - -
    -
    - - - - -
    int(* hwloc_backend::get_pci_busid_cpuset) (struct hwloc_backend *backend, struct hwloc_pcidev_attr_s *busid, hwloc_bitmap_t cpuset)
    -
    - -

    Callback to retrieve the locality of a PCI object. Called by the PCI core when attaching PCI hierarchy to CPU objects. May be NULL.

    - -
    -
    - -

    ◆ is_thissystem

    - -
    -
    - - - - -
    int hwloc_backend::is_thissystem
    -
    - -

    Backend-specific 'is_thissystem' property. Set to 0 if the backend disables the thissystem flag for this topology (e.g. loading from xml or synthetic string, or using a different fsroot on Linux, or a x86 CPUID dump). Set to -1 if the backend doesn't care (default).

    - -
    -
    - -

    ◆ phases

    - -
    -
    - - - - -
    unsigned hwloc_backend::phases
    -
    - -

    Discovery phases performed by this component, possibly without some of them if excluded by other components. OR'ed set of hwloc_disc_phase_t.

    - -
    -
    - -

    ◆ private_data

    - -
    -
    - - - - -
    void* hwloc_backend::private_data
    -
    - -

    Backend private data, or NULL if none.

    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - -
    -
    -Data Fields
    -
    -
    hwloc_component Struct Reference
    Components and Plugins: Generic components
    -
    -
    - -

    #include <plugins.h>

    - - - - - - - - - - - - - - -

    -Data Fields

    unsigned abi
     
    int(* init )(unsigned long flags)
     
    void(* finalize )(unsigned long flags)
     
    hwloc_component_type_t type
     
    unsigned long flags
     
    void * data
     
    -

    Detailed Description

    -

    Generic component structure.

    -

    Generic components structure, either statically listed by configure in static-components.h or dynamically loaded as a plugin.

    -

    Field Documentation

    - -

    ◆ abi

    - -
    -
    - - - - -
    unsigned hwloc_component::abi
    -
    - -

    Component ABI version, set to HWLOC_COMPONENT_ABI.

    - -
    -
    - -

    ◆ data

    - -
    -
    - - - - -
    void* hwloc_component::data
    -
    - -

    Component data, pointing to a struct hwloc_disc_component or struct hwloc_xml_component.

    - -
    -
    - -

    ◆ finalize

    - -
    -
    - - - - -
    void(* hwloc_component::finalize) (unsigned long flags)
    -
    - -

    Process-wide component termination callback.

    -

    This optional callback is called after unregistering the component from the hwloc core (before unloading the plugin).

    -

    flags is always 0 for now.

    -
    Note
    If the component uses ltdl for loading its own plugins, it should load/unload them only in init() and finalize(), to avoid race conditions with hwloc's use of ltdl.
    - -
    -
    - -

    ◆ flags

    - -
    -
    - - - - -
    unsigned long hwloc_component::flags
    -
    - -

    Component flags, unused for now.

    - -
    -
    - -

    ◆ init

    - -
    -
    - - - - -
    int(* hwloc_component::init) (unsigned long flags)
    -
    - -

    Process-wide component initialization callback.

    -

    This optional callback is called when the component is registered to the hwloc core (after loading the plugin).

    -

    When the component is built as a plugin, this callback should call hwloc_check_plugin_namespace() and return an negative error code on error.

    -

    flags is always 0 for now.

    -
    Returns
    0 on success, or a negative code on error.
    -
    Note
    If the component uses ltdl for loading its own plugins, it should load/unload them only in init() and finalize(), to avoid race conditions with hwloc's use of ltdl.
    - -
    -
    - -

    ◆ type

    - -
    -
    - - - - -
    hwloc_component_type_t hwloc_component::type
    -
    - -

    Component type.

    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - -
    -
    -
    Hardware Locality (hwloc) Introduction
    -
    -
    -

    Portable abstraction of hierarchical architectures for high-performance computing

    -
    -

    -

    - See also Further Reading -or the Related pages tab above - for links to more sections about hwloc concepts. -
    -

    -

    -

    -

    -

    -hwloc Summary

    -

    hwloc provides command line tools and a C API to obtain the hierarchical map of key computing elements within a node, such as: NUMA memory nodes, shared caches, processor packages, dies and cores, processing units (logical processors or "threads") and even I/O devices. hwloc also gathers various attributes such as cache and memory information, and is portable across a variety of different operating systems and platforms.

    -

    hwloc primarily aims at helping high-performance computing (HPC) applications, but is also applicable to any project seeking to exploit code and/or data locality on modern computing platforms.

    -

    hwloc supports the following operating systems:

    -
      -
    • -Linux (including old kernels not having sysfs topology information, with knowledge of cpusets, ScaleMP vSMP support, etc.) on all supported hardware, including Intel Xeon Phi and NumaScale NumaConnect.
      • -
    • -Solaris (with support for processor sets and logical domains)
      • -
    • -AIX
      • -
    • -Darwin / OS X
      • -
    • -FreeBSD and its variants (such as kFreeBSD/GNU)
      • -
    • -NetBSD
      • -
    • -HP-UX
      • -
    • -Microsoft Windows
      • -
    • -IBM BlueGene/Q Compute Node Kernel (CNK)
      • -
    -

    Since it uses standard Operating System information, hwloc's support is mostly independant from the processor type (x86, powerpc, ...) and just relies on the Operating System support. The main exception is BSD operating systems (NetBSD, FreeBSD, etc.) because they do not provide support topology information, hence hwloc uses an x86-only CPUID-based backend (which can be used for other OSes too, see the Components and plugins section).

    -

    To check whether hwloc works on a particular machine, just try to build it and run lstopo or lstopo-no-graphics. If some things do not look right (e.g. bogus or missing cache information), see Questions and Bugs.

    -

    hwloc only reports the number of processors on unsupported operating systems; no topology information is available.

    -

    For development and debugging purposes, hwloc also offers the ability to work on "fake" topologies:

    - -

    hwloc can display the topology in a human-readable format, either in graphical mode (X11), or by exporting in one of several different formats, including: plain text, LaTeX tikzpicture, PDF, PNG, and FIG (see Command-line Examples below). Note that some of the export formats require additional support libraries.

    -

    hwloc offers a programming interface for manipulating topologies and objects. It also brings a powerful CPU bitmap API that is used to describe topology objects location on physical/logical processors. See the Programming Interface below. It may also be used to binding applications onto certain cores or memory nodes. Several utility programs are also provided to ease command-line manipulation of topology objects, binding of processes, and so on.

    -

    Perl bindings are available from Bernd Kallies on CPAN.

    -

    Python bindings are available from Guy Streeter:

    -

    -

    -

    -

    -hwloc Installation

    -

    The generic installation procedure for both hwloc and netloc is described in Installation.

    -

    The hwloc command-line tool "lstopo" produces human-readable topology maps, as mentioned above. It can also export maps to the "fig" file format. Support for PDF, Postscript, and PNG exporting is provided if the "Cairo" development package (usually cairo-devel or libcairo2-dev) can be found in "lstopo" when hwloc is configured and build.

    -

    The hwloc core may also benefit from the following development packages:

      -
    • -

      libpciaccess for full I/O device discovery (libpciaccess-devel or libpciaccess-dev package). On Linux, PCI discovery may still be performed (without vendor/device names) even if libpciaccess cannot be used.

      -

      -
      • -
    • -AMD or NVIDIA OpenCL implementations for OpenCL device discovery.
      • -
    • -the NVIDIA CUDA Toolkit for CUDA device discovery. See How do I enable CUDA and select which CUDA version to use?.
      • -
    • -the NVIDIA Management Library (NVML) for NVML device discovery. It is included in CUDA since version 8.0. Older NVML releases were available within the NVIDIA GPU Deployment Kit from https://developer.nvidia.com/gpu-deployment-kit .
      • -
    • -the NV-CONTROL X extension library (NVCtrl) for NVIDIA display discovery. The relevant development package is usually libXNVCtrl-devel or libxnvctrl-dev. It is also available within nvidia-settings from ftp://download.nvidia.com/XFree86/nvidia-settings/ and https://github.com/NVIDIA/nvidia-settings/ .
      • -
    • -the AMD ROCm SMI library for RSMI device discovery. The relevant development package is usually rocm-smi-lib64 or librocm-smi-dev. See How do I enable ROCm SMI and select which version to use?.
      • -
    • -the oneAPI Level Zero library. The relevant development package is usually level-zero-dev or level-zero-devel.
      • -
    • -libxml2 for full XML import/export support (otherwise, the internal minimalistic parser will only be able to import XML files that were exported by the same hwloc release). See Importing and exporting topologies from/to XML files for details. The relevant development package is usually libxml2-devel or libxml2-dev.
      • -
    • -libudev on Linux for easier discovery of OS device information (otherwise hwloc will try to manually parse udev raw files). The relevant development package is usually libudev-devel or libudev-dev.
      • -
    • -libtool's ltdl library for dynamic plugin loading if the native dlopen cannot be used. The relevant development package is usually libtool-ltdl-devel or libltdl-dev.
      • -
    -

    PCI and XML support may be statically built inside the main hwloc library, or as separate dynamically-loaded plugins (see the Components and plugins section).

    -

    Note that because of the possibility of GPL taint, the pciutils library libpci will not be used (remember that hwloc is BSD-licensed).

    -

    -

    -

    -

    -Command-line Examples

    -

    On a 4-package 2-core machine with hyper-threading, the lstopo tool may show the following graphical output:

    -
    - -
    -

    Here's the equivalent output in textual form:

    -
    Machine
-  NUMANode L#0 (P#0)
-  Package L#0 + L3 L#0 (4096KB)
-    L2 L#0 (1024KB) + L1 L#0 (16KB) + Core L#0
-      PU L#0 (P#0)
-      PU L#1 (P#8)
-    L2 L#1 (1024KB) + L1 L#1 (16KB) + Core L#1
-      PU L#2 (P#4)
-      PU L#3 (P#12)
-  Package L#1 + L3 L#1 (4096KB)
-    L2 L#2 (1024KB) + L1 L#2 (16KB) + Core L#2
-      PU L#4 (P#1)
-      PU L#5 (P#9)
-    L2 L#3 (1024KB) + L1 L#3 (16KB) + Core L#3
-      PU L#6 (P#5)
-      PU L#7 (P#13)
-  Package L#2 + L3 L#2 (4096KB)
-    L2 L#4 (1024KB) + L1 L#4 (16KB) + Core L#4
-      PU L#8 (P#2)
-      PU L#9 (P#10)
-    L2 L#5 (1024KB) + L1 L#5 (16KB) + Core L#5
-      PU L#10 (P#6)
-      PU L#11 (P#14)
-  Package L#3 + L3 L#3 (4096KB)
-    L2 L#6 (1024KB) + L1 L#6 (16KB) + Core L#6
-      PU L#12 (P#3)
-      PU L#13 (P#11)
-    L2 L#7 (1024KB) + L1 L#7 (16KB) + Core L#7
-      PU L#14 (P#7)
-      PU L#15 (P#15)
-

    Note that there is also an equivalent output in XML that is meant for exporting/importing topologies but it is hardly readable to human-beings (see Importing and exporting topologies from/to XML files for details).

    -

    On a 4-package 2-core Opteron NUMA machine (with two core cores disallowed by the administrator), the lstopo tool may show the following graphical output (with --disallowed for displaying disallowed objects):

    -
    - -
    -

    Here's the equivalent output in textual form:

    -
    Machine (32GB total)
-  Package L#0
-    NUMANode L#0 (P#0 8190MB)
-    L2 L#0 (1024KB) + L1 L#0 (64KB) + Core L#0 + PU L#0 (P#0)
-    L2 L#1 (1024KB) + L1 L#1 (64KB) + Core L#1 + PU L#1 (P#1)
-  Package L#1
-    NUMANode L#1 (P#1 8192MB)
-    L2 L#2 (1024KB) + L1 L#2 (64KB) + Core L#2 + PU L#2 (P#2)
-    L2 L#3 (1024KB) + L1 L#3 (64KB) + Core L#3 + PU L#3 (P#3)
-  Package L#2
-    NUMANode L#2 (P#2 8192MB)
-    L2 L#4 (1024KB) + L1 L#4 (64KB) + Core L#4 + PU L#4 (P#4)
-    L2 L#5 (1024KB) + L1 L#5 (64KB) + Core L#5 + PU L#5 (P#5)
-  Package L#3
-    NUMANode L#3 (P#3 8192MB)
-    L2 L#6 (1024KB) + L1 L#6 (64KB) + Core L#6 + PU L#6 (P#6)
-    L2 L#7 (1024KB) + L1 L#7 (64KB) + Core L#7 + PU L#7 (P#7)
-

    On a 2-package quad-core Xeon (pre-Nehalem, with 2 dual-core dies into each package):

    -
    - -
    -

    Here's the same output in textual form:

    -
    Machine (total 16GB)
-  NUMANode L#0 (P#0 16GB)
-  Package L#0
-    L2 L#0 (4096KB)
-      L1 L#0 (32KB) + Core L#0 + PU L#0 (P#0)
-      L1 L#1 (32KB) + Core L#1 + PU L#1 (P#4)
-    L2 L#1 (4096KB)
-      L1 L#2 (32KB) + Core L#2 + PU L#2 (P#2)
-      L1 L#3 (32KB) + Core L#3 + PU L#3 (P#6)
-  Package L#1
-    L2 L#2 (4096KB)
-      L1 L#4 (32KB) + Core L#4 + PU L#4 (P#1)
-      L1 L#5 (32KB) + Core L#5 + PU L#5 (P#5)
-    L2 L#3 (4096KB)
-      L1 L#6 (32KB) + Core L#6 + PU L#6 (P#3)
-      L1 L#7 (32KB) + Core L#7 + PU L#7 (P#7)
-

    -

    -

    -

    -Programming Interface

    -

    The basic interface is available in hwloc.h. Some higher-level functions are available in hwloc/helper.h to reduce the need to manually manipulate objects and follow links between them. Documentation for all these is provided later in this document. Developers may also want to look at hwloc/inlines.h which contains the actual inline code of some hwloc.h routines, and at this document, which provides good higher-level topology traversal examples.

    -

    To precisely define the vocabulary used by hwloc, a Terms and Definitions section is available and should probably be read first.

    -

    Each hwloc object contains a cpuset describing the list of processing units that it contains. These bitmaps may be used for CPU binding and Memory binding. hwloc offers an extensive bitmap manipulation interface in hwloc/bitmap.h.

    -

    Moreover, hwloc also comes with additional helpers for interoperability with several commonly used environments. See the Interoperability With Other Software section for details.

    -

    The complete API documentation is available in a full set of HTML pages, man pages, and self-contained PDF files (formatted for both both US letter and A4 formats) in the source tarball in doc/doxygen-doc/.

    -

    NOTE: If you are building the documentation from a Git clone, you will need to have Doxygen and pdflatex installed – the documentation will be built during the normal "make" process. The documentation is installed during "make install" to $prefix/share/doc/hwloc/ and your systems default man page tree (under $prefix, of course).

    -

    -Portability

    -

    Operating System have varying support for CPU and memory binding, e.g. while some Operating Systems provide interfaces for all kinds of CPU and memory bindings, some others provide only interfaces for a limited number of kinds of CPU and memory binding, and some do not provide any binding interface at all. Hwloc's binding functions would then simply return the ENOSYS error (Function not implemented), meaning that the underlying Operating System does not provide any interface for them. CPU binding and Memory binding provide more information on which hwloc binding functions should be preferred because interfaces for them are usually available on the supported Operating Systems.

    -

    Similarly, the ability of reporting topology information varies from one platform to another. As shown in Command-line Examples, hwloc can obtain information on a wide variety of hardware topologies. However, some platforms and/or operating system versions will only report a subset of this information. For example, on an PPC64-based system with 8 cores (each with 2 hardware threads) running a default 2.6.18-based kernel from RHEL 5.4, hwloc is only able to glean information about NUMA nodes and processor units (PUs). No information about caches, packages, or cores is available.

    -

    Here's the graphical output from lstopo on this platform when Simultaneous Multi-Threading (SMT) is enabled:

    -
    - -
    -

    And here's the graphical output from lstopo on this platform when SMT is disabled:

    -
    - -
    -

    Notice that hwloc only sees half the PUs when SMT is disabled. PU L#6, for example, seems to change location from NUMA node #0 to #1. In reality, no PUs "moved" – they were simply re-numbered when hwloc only saw half as many (see also Logical index in Indexes and Sets). Hence, PU L#6 in the SMT-disabled picture probably corresponds to PU L#12 in the SMT-enabled picture.

    -

    This same "PUs have disappeared" effect can be seen on other platforms – even platforms / OSs that provide much more information than the above PPC64 system. This is an unfortunate side-effect of how operating systems report information to hwloc.

    -

    Note that upgrading the Linux kernel on the same PPC64 system mentioned above to 2.6.34, hwloc is able to discover all the topology information. The following picture shows the entire topology layout when SMT is enabled:

    -
    - -
    -

    Developers using the hwloc API or XML output for portable applications should therefore be extremely careful to not make any assumptions about the structure of data that is returned. For example, per the above reported PPC topology, it is not safe to assume that PUs will always be descendants of cores.

    -

    Additionally, future hardware may insert new topology elements that are not available in this version of hwloc. Long-lived applications that are meant to span multiple different hardware platforms should also be careful about making structure assumptions. For example, a new element may someday exist between a core and a PU.

    -

    -API Example

    -

    The following small C example (available in the source tree as ``doc/examples/hwloc-hello.c'') prints the topology of the machine and performs some thread and memory binding. More examples are available in the doc/examples/ directory of the source tree.

    -
    /* Example hwloc API program.
    -
    *
    -
    * See other examples under doc/examples/ in the source tree
    -
    * for more details.
    -
    *
    -
    * Copyright © 2009-2016 Inria. All rights reserved.
    -
    * Copyright © 2009-2011 Université Bordeaux
    -
    * Copyright © 2009-2010 Cisco Systems, Inc. All rights reserved.
    -
    * See COPYING in top-level directory.
    -
    *
    -
    * hwloc-hello.c
    -
    */
    -
    -
    #include "hwloc.h"
    -
    -
    #include <errno.h>
    -
    #include <stdio.h>
    -
    #include <string.h>
    -
    -
    static void print_children(hwloc_topology_t topology, hwloc_obj_t obj,
    -
    int depth)
    -
    {
    -
    char type[32], attr[1024];
    -
    unsigned i;
    -
    -
    hwloc_obj_type_snprintf(type, sizeof(type), obj, 0);
    -
    printf("%*s%s", 2*depth, "", type);
    -
    if (obj->os_index != (unsigned) -1)
    -
    printf("#%u", obj->os_index);
    -
    hwloc_obj_attr_snprintf(attr, sizeof(attr), obj, " ", 0);
    -
    if (*attr)
    -
    printf("(%s)", attr);
    -
    printf("\n");
    -
    for (i = 0; i < obj->arity; i++) {
    -
    print_children(topology, obj->children[i], depth + 1);
    -
    }
    -
    }
    -
    -
    int main(void)
    -
    {
    -
    int depth;
    -
    unsigned i, n;
    -
    unsigned long size;
    -
    int levels;
    -
    char string[128];
    -
    int topodepth;
    -
    void *m;
    -
    hwloc_topology_t topology;
    -
    hwloc_cpuset_t cpuset;
    -
    hwloc_obj_t obj;
    -
    -
    /* Allocate and initialize topology object. */
    -
    hwloc_topology_init(&topology);
    -
    -
    /* ... Optionally, put detection configuration here to ignore
    -
    some objects types, define a synthetic topology, etc....
    -
    -
    The default is to detect all the objects of the machine that
    -
    the caller is allowed to access. See Configure Topology
    -
    Detection. */
    -
    -
    /* Perform the topology detection. */
    -
    hwloc_topology_load(topology);
    -
    -
    /* Optionally, get some additional topology information
    -
    in case we need the topology depth later. */
    -
    topodepth = hwloc_topology_get_depth(topology);
    -
    -
    /*****************************************************************
    -
    * First example:
    -
    * Walk the topology with an array style, from level 0 (always
    -
    * the system level) to the lowest level (always the proc level).
    -
    *****************************************************************/
    -
    for (depth = 0; depth < topodepth; depth++) {
    -
    printf("*** Objects at level %d\n", depth);
    -
    for (i = 0; i < hwloc_get_nbobjs_by_depth(topology, depth);
    -
    i++) {
    -
    hwloc_obj_type_snprintf(string, sizeof(string),
    -
    hwloc_get_obj_by_depth(topology, depth, i), 0);
    -
    printf("Index %u: %s\n", i, string);
    -
    }
    -
    }
    -
    -
    /*****************************************************************
    -
    * Second example:
    -
    * Walk the topology with a tree style.
    -
    *****************************************************************/
    -
    printf("*** Printing overall tree\n");
    -
    print_children(topology, hwloc_get_root_obj(topology), 0);
    -
    -
    /*****************************************************************
    -
    * Third example:
    -
    * Print the number of packages.
    -
    *****************************************************************/
    -
    depth = hwloc_get_type_depth(topology, HWLOC_OBJ_PACKAGE);
    -
    if (depth == HWLOC_TYPE_DEPTH_UNKNOWN) {
    -
    printf("*** The number of packages is unknown\n");
    -
    } else {
    -
    printf("*** %u package(s)\n",
    -
    hwloc_get_nbobjs_by_depth(topology, depth));
    -
    }
    -
    -
    /*****************************************************************
    -
    * Fourth example:
    -
    * Compute the amount of cache that the first logical processor
    -
    * has above it.
    -
    *****************************************************************/
    -
    levels = 0;
    -
    size = 0;
    -
    for (obj = hwloc_get_obj_by_type(topology, HWLOC_OBJ_PU, 0);
    -
    obj;
    -
    obj = obj->parent)
    -
    if (hwloc_obj_type_is_cache(obj->type)) {
    -
    levels++;
    -
    size += obj->attr->cache.size;
    -
    }
    -
    printf("*** Logical processor 0 has %d caches totaling %luKB\n",
    -
    levels, size / 1024);
    -
    -
    /*****************************************************************
    -
    * Fifth example:
    -
    * Bind to only one thread of the last core of the machine.
    -
    *
    -
    * First find out where cores are, or else smaller sets of CPUs if
    -
    * the OS doesn't have the notion of a "core".
    -
    *****************************************************************/
    -
    depth = hwloc_get_type_or_below_depth(topology, HWLOC_OBJ_CORE);
    -
    -
    /* Get last core. */
    -
    obj = hwloc_get_obj_by_depth(topology, depth,
    -
    hwloc_get_nbobjs_by_depth(topology, depth) - 1);
    -
    if (obj) {
    -
    /* Get a copy of its cpuset that we may modify. */
    -
    cpuset = hwloc_bitmap_dup(obj->cpuset);
    -
    -
    /* Get only one logical processor (in case the core is
    -
    SMT/hyper-threaded). */
    -
    hwloc_bitmap_singlify(cpuset);
    -
    -
    /* And try to bind ourself there. */
    -
    if (hwloc_set_cpubind(topology, cpuset, 0)) {
    -
    char *str;
    -
    int error = errno;
    -
    hwloc_bitmap_asprintf(&str, obj->cpuset);
    -
    printf("Couldn't bind to cpuset %s: %s\n", str, strerror(error));
    -
    free(str);
    -
    }
    -
    -
    /* Free our cpuset copy */
    -
    hwloc_bitmap_free(cpuset);
    -
    }
    -
    -
    /*****************************************************************
    -
    * Sixth example:
    -
    * Allocate some memory on the last NUMA node, bind some existing
    -
    * memory to the last NUMA node.
    -
    *****************************************************************/
    -
    /* Get last node. There's always at least one. */
    -
    n = hwloc_get_nbobjs_by_type(topology, HWLOC_OBJ_NUMANODE);
    -
    obj = hwloc_get_obj_by_type(topology, HWLOC_OBJ_NUMANODE, n - 1);
    -
    -
    size = 1024*1024;
    -
    m = hwloc_alloc_membind(topology, size, obj->nodeset,
    -
    HWLOC_MEMBIND_BIND, HWLOC_MEMBIND_BYNODESET);
    -
    hwloc_free(topology, m, size);
    -
    -
    m = malloc(size);
    -
    hwloc_set_area_membind(topology, m, size, obj->nodeset,
    -
    HWLOC_MEMBIND_BIND, HWLOC_MEMBIND_BYNODESET);
    -
    free(m);
    -
    -
    /* Destroy topology object. */
    -
    hwloc_topology_destroy(topology);
    -
    -
    return 0;
    -
    }
    -
    hwloc_cpuset_t
    hwloc_bitmap_t hwloc_cpuset_t
    A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
    Definition: hwloc.h:140
    -
    HWLOC_OBJ_NUMANODE
    @ HWLOC_OBJ_NUMANODE
    NUMA node. An object that contains memory that is directly and byte-accessible to the host processors...
    Definition: hwloc.h:236
    -
    HWLOC_OBJ_PACKAGE
    @ HWLOC_OBJ_PACKAGE
    Physical package. The physical package that usually gets inserted into a socket on the motherboard....
    Definition: hwloc.h:191
    -
    HWLOC_OBJ_PU
    @ HWLOC_OBJ_PU
    Processing Unit, or (Logical) Processor. An execution unit (may share a core with some other logical ...
    Definition: hwloc.h:201
    -
    HWLOC_OBJ_CORE
    @ HWLOC_OBJ_CORE
    Core. A computation unit (may be shared by several PUs, aka logical processors).
    Definition: hwloc.h:197
    -
    hwloc_topology_init
    int hwloc_topology_init(hwloc_topology_t *topologyp)
    Allocate a topology context.
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:692
    -
    hwloc_topology_destroy
    void hwloc_topology_destroy(hwloc_topology_t topology)
    Terminate and free a topology context.
    -
    hwloc_topology_load
    int hwloc_topology_load(hwloc_topology_t topology)
    Build the actual topology.
    -
    hwloc_get_nbobjs_by_depth
    unsigned hwloc_get_nbobjs_by_depth(hwloc_topology_t topology, int depth)
    Returns the width of level at depth depth.
    -
    hwloc_get_root_obj
    static hwloc_obj_t hwloc_get_root_obj(hwloc_topology_t topology)
    Returns the top-object of the topology-tree.
    -
    hwloc_get_obj_by_depth
    hwloc_obj_t hwloc_get_obj_by_depth(hwloc_topology_t topology, int depth, unsigned idx)
    Returns the topology object at logical index idx from depth depth.
    -
    hwloc_get_obj_by_type
    static hwloc_obj_t hwloc_get_obj_by_type(hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx)
    Returns the topology object at logical index idx with type type.
    -
    hwloc_get_nbobjs_by_type
    static int hwloc_get_nbobjs_by_type(hwloc_topology_t topology, hwloc_obj_type_t type)
    Returns the width of level type type.
    -
    hwloc_get_type_or_below_depth
    static int hwloc_get_type_or_below_depth(hwloc_topology_t topology, hwloc_obj_type_t type)
    Returns the depth of objects of type type or below.
    -
    hwloc_get_type_depth
    int hwloc_get_type_depth(hwloc_topology_t topology, hwloc_obj_type_t type)
    Returns the depth of objects of type type.
    -
    hwloc_topology_get_depth
    int hwloc_topology_get_depth(hwloc_topology_t restrict topology)
    Get the depth of the hierarchical tree of objects.
    -
    HWLOC_TYPE_DEPTH_UNKNOWN
    @ HWLOC_TYPE_DEPTH_UNKNOWN
    No object of given type exists in the topology.
    Definition: hwloc.h:822
    -
    hwloc_obj_attr_snprintf
    int hwloc_obj_attr_snprintf(char *restrict string, size_t size, hwloc_obj_t obj, const char *restrict separator, int verbose)
    Stringify the attributes of a given topology object into a human-readable form.
    -
    hwloc_obj_type_snprintf
    int hwloc_obj_type_snprintf(char *restrict string, size_t size, hwloc_obj_t obj, int verbose)
    Stringify the type of a given topology object into a human-readable form.
    -
    hwloc_set_cpubind
    int hwloc_set_cpubind(hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags)
    Bind current process or thread on CPUs given in physical bitmap set.
    -
    hwloc_alloc_membind
    void * hwloc_alloc_membind(hwloc_topology_t topology, size_t len, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags)
    Allocate some memory on NUMA memory nodes specified by set.
    -
    hwloc_free
    int hwloc_free(hwloc_topology_t topology, void *addr, size_t len)
    Free memory that was previously allocated by hwloc_alloc() or hwloc_alloc_membind().
    -
    hwloc_set_area_membind
    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)
    Bind the already-allocated memory identified by (addr, len) to the NUMA node(s) specified by set.
    -
    HWLOC_MEMBIND_BYNODESET
    @ HWLOC_MEMBIND_BYNODESET
    Consider the bitmap argument as a nodeset.
    Definition: hwloc.h:1509
    -
    HWLOC_MEMBIND_BIND
    @ HWLOC_MEMBIND_BIND
    Allocate memory on the specified nodes.
    Definition: hwloc.h:1421
    -
    hwloc_obj_type_is_cache
    int hwloc_obj_type_is_cache(hwloc_obj_type_t type)
    Check whether an object type is a CPU Cache (Data, Unified or Instruction).
    -
    hwloc_bitmap_asprintf
    int hwloc_bitmap_asprintf(char **strp, hwloc_const_bitmap_t bitmap)
    Stringify a bitmap into a newly allocated string.
    -
    hwloc_bitmap_free
    void hwloc_bitmap_free(hwloc_bitmap_t bitmap)
    Free bitmap bitmap.
    -
    hwloc_bitmap_singlify
    int hwloc_bitmap_singlify(hwloc_bitmap_t bitmap)
    Keep a single index among those set in bitmap bitmap.
    -
    hwloc_bitmap_dup
    hwloc_bitmap_t hwloc_bitmap_dup(hwloc_const_bitmap_t bitmap)
    Duplicate bitmap bitmap by allocating a new bitmap and copying bitmap contents.
    -
    hwloc_obj
    Structure of a topology object.
    Definition: hwloc.h:396
    -
    hwloc_obj::children
    struct hwloc_obj ** children
    Normal children, children[0 .. arity -1].
    Definition: hwloc.h:456
    -
    hwloc_obj::nodeset
    hwloc_nodeset_t nodeset
    NUMA nodes covered by this object or containing this object.
    Definition: hwloc.h:540
    -
    hwloc_obj::os_index
    unsigned os_index
    OS-provided physical index number. It is not guaranteed unique across the entire machine,...
    Definition: hwloc.h:401
    -
    hwloc_obj::cpuset
    hwloc_cpuset_t cpuset
    CPUs covered by this object.
    Definition: hwloc.h:512
    -
    hwloc_obj::arity
    unsigned arity
    Number of normal children. Memory, Misc and I/O children are not listed here but rather in their dedi...
    Definition: hwloc.h:452
    -
    hwloc_obj::type
    hwloc_obj_type_t type
    Type of object.
    Definition: hwloc.h:398
    -
    hwloc_obj::attr
    union hwloc_obj_attr_u * attr
    Object type-specific Attributes, may be NULL if no attribute value was found.
    Definition: hwloc.h:415
    -
    hwloc_obj::parent
    struct hwloc_obj * parent
    Parent, NULL if root (Machine object)
    Definition: hwloc.h:446
    -
    hwloc_obj_attr_u::cache
    struct hwloc_obj_attr_u::hwloc_cache_attr_s cache
    -
    hwloc_obj_attr_u::hwloc_cache_attr_s::size
    hwloc_uint64_t size
    Size of cache in bytes.
    Definition: hwloc.h:617
    -

    hwloc provides a pkg-config executable to obtain relevant compiler and linker flags. For example, it can be used thusly to compile applications that utilize the hwloc library (assuming GNU Make):

    -
    CFLAGS += $(shell pkg-config --cflags hwloc)
-LDLIBS += $(shell pkg-config --libs hwloc)
-
-hwloc-hello: hwloc-hello.c
-        $(CC) hwloc-hello.c $(CFLAGS) -o hwloc-hello $(LDLIBS)
-

    On a machine 2 processor packages – each package of which has two processing cores – the output from running hwloc-hello could be something like the following:

    -
    shell$ ./hwloc-hello
-*** Objects at level 0
-Index 0: Machine
-*** Objects at level 1
-Index 0: Package#0
-Index 1: Package#1
-*** Objects at level 2
-Index 0: Core#0
-Index 1: Core#1
-Index 2: Core#3
-Index 3: Core#2
-*** Objects at level 3
-Index 0: PU#0
-Index 1: PU#1
-Index 2: PU#2
-Index 3: PU#3
-*** Printing overall tree
-Machine
-  Package#0
-    Core#0
-      PU#0
-    Core#1
-      PU#1
-  Package#1
-    Core#3
-      PU#2
-    Core#2
-      PU#3
-*** 2 package(s)
-*** Logical processor 0 has 0 caches totaling 0KB
-shell$ 
-

    -

    -

    -

    -History / Credits

    -

    hwloc is the evolution and merger of the libtopology project and the Portable Linux Processor Affinity (PLPA) (https://www.open-mpi.org/projects/plpa/) project. Because of functional and ideological overlap, these two code bases and ideas were merged and released under the name "hwloc" as an Open MPI sub-project.

    -

    libtopology was initially developed by the Inria Runtime Team-Project. PLPA was initially developed by the Open MPI development team as a sub-project. Both are now deprecated in favor of hwloc, which is distributed as an Open MPI sub-project.

    -

    -

    -

    -
    -
    - - - - - - - -
    -
    -
    Terms and Definitions
    -
    -
    -

    -

    -

    -

    -Objects

    -
    -
    Object
    -

    Interesting kind of part of the system, such as a Core, a L2Cache, a NUMA memory node, etc. The different types detected by hwloc are detailed in the hwloc_obj_type_t enumeration.

    -

    There are four kinds of Objects: Memory (NUMA nodes and Memory-side caches), I/O (Bridges, PCI and OS devices), Misc, and Normal (everything else, including Machine, Package, Die, Core, PU, CPU Caches, etc.). Normal and Memory objects have (non-NULL) CPU sets and nodesets, while I/O and Misc don't.

    -

    Objects are topologically sorted by locality (CPU and node sets) into a tree (see Hierarchy, Tree and Levels).

    -

    -
    -
    Processing Unit (PU)
    -

    The smallest processing element that can be represented by a hwloc object. It may be a single-core processor, a core of a multicore processor, or a single thread in a SMT processor (also sometimes called "Logical processor", not to be confused with "Logical index of a processor"). hwloc's PU acronym stands for Processing Unit.

    -

    -
    -
    Package
    -

    A processor Package is the physical package that usually gets inserted into a socket on the motherboard. It is also often called a physical processor or a CPU even if these names bring confusion with respect to cores and processing units. A processor package usually contains multiple cores (and may also be composed of multiple dies). hwloc Package objects were called Sockets up to hwloc 1.10.

    -

    -
    -
    NUMA Node
    -

    An object that contains memory that is directly and byte-accessible to the host processors. It is usually close to some cores as specified by its CPU set. Hence it is attached as a memory child of the object that groups those cores together, for instance a Package objects with 4 Core children (see Hierarchy, Tree and Levels).

    -

    -
    -
    Memory-side Cache
    -

    A cache in front of a specific memory region (e.g. a range of physical addresses). It caches all accesses to that region without caring about which core issued the request. This is the opposite of usual CPU caches where only accesses from the local cores are cached, without caring about the target memory.

    -

    In hwloc, memory-side caches are memory objects placed between their local CPU objects (parent) and the target NUMA node memory (child).

    -
    -
    -

    -

    -

    -

    -Indexes and Sets

    -
    -
    OS or physical index
    -

    The index that the operating system (OS) uses to identify the object. This may be completely arbitrary, non-unique, non-contiguous, not representative of logical proximity, and may depend on the BIOS configuration. That is why hwloc almost never uses them, only in the default lstopo output (P#x) and cpuset masks. See also Should I use logical or physical/OS indexes? and how?.

    -

    -
    -
    Logical index
    -

    Index to uniquely identify objects of the same type and depth, automatically computed by hwloc according to the topology. It expresses logical proximity in a generic way, i.e. objects which have adjacent logical indexes are adjacent in the topology. That is why hwloc almost always uses it in its API, since it expresses logical proximity. They can be shown (as L#x) by lstopo thanks to the -l option. This index is always linear and in the range [0, num_objs_same_type_same_level-1]. Think of it as ``cousin rank.'' The ordering is based on topology first, and then on OS CPU numbers, so it is stable across everything except firmware CPU renumbering. "Logical index" should not be confused with "Logical processor". A "Logical - processor" (which in hwloc we rather call "processing unit" to avoid the confusion) has both a physical index (as chosen arbitrarily by BIOS/OS) and a logical index (as computed according to logical proximity by hwloc). See also Should I use logical or physical/OS indexes? and how?.

    -

    -
    -
    CPU set
    -

    The set of processing units (PU) logically included in an object (if it makes sense). They are always expressed using physical processor numbers (as announced by the OS). They are implemented as the hwloc_bitmap_t opaque structure. hwloc CPU sets are just masks, they do not have any relation with an operating system actual binding notion like Linux' cpusets. I/O and Misc objects do not have CPU sets while all Normal and Memory objects have non-NULL CPU sets.

    -

    -
    -
    Node set
    -

    The set of NUMA memory nodes logically included in an object (if it makes sense). They are always expressed using physical node numbers (as announced by the OS). They are implemented with the hwloc_bitmap_t opaque structure. as bitmaps. I/O and Misc objects do not have Node sets while all Normal and Memory objects have non-NULL nodesets.

    -

    -
    -
    Bitmap
    -

    A possibly-infinite set of bits used for describing sets of objects such as CPUs (CPU sets) or memory nodes (Node sets). They are implemented with the hwloc_bitmap_t opaque structure.

    -

    -
    -
    -

    -

    -

    -

    -Hierarchy, Tree and Levels

    -
    -
    Parent object
    -

    The object logically containing the current object, for example because its CPU set includes the CPU set of the current object. All objects have a non-NULL parent, except the root of the topology (Machine object).

    -

    -
    -
    Ancestor object
    -

    The parent object, or its own parent, and so on.

    -

    -
    -
    Children object(s)
    -

    The object (or objects) contained in the current object because their CPU set is included in the CPU set of the current object. Each object may also contain separated lists for Memory, I/O and Misc object children.

    -

    -
    -
    Arity
    -

    The number of normal children of an object. There are also specific arities for Memory, I/O and Misc children.

    -

    -
    -
    Sibling objects
    -

    Objects in the same children list, which all of them are normal children of the same parent, or all of them are Memory children of the same parent, or I/O children, or Misc. They usually have the same type (and hence are cousins, as well). But they may not if the topology is asymmetric.

    -

    -
    -
    Sibling rank
    -

    Index to uniquely identify objects which have the same parent, and is always in the range [0, arity-1] (respectively memory_arity, io_arity or misc_arity for Memory, I/O and Misc children of a parent).

    -

    -
    -
    Cousin objects
    -

    Objects of the same type (and depth) as the current object, even if they do not have the same parent.

    -

    -
    -
    Level
    -

    Set of objects of the same type and depth. All these objects are cousins.

    -

    Memory, I/O and Misc objects also have their own specific levels and (virtual) depth.

    -

    -
    -
    Depth
    -

    Nesting level in the object tree, starting from the root object. If the topology is symmetric, the depth of a child is equal to the parent depth plus one, and an object depth is also equal to the number of parent/child links between the root object and the given object. If the topology is asymmetric, the difference between some parent and child depths may be larger than one when some intermediate levels (for instance groups) are missing in only some parts of the machine.

    -

    The depth of the Machine object is always 0 since it is always the root of the topology. The depth of PU objects is equal to the number of levels in the topology minus one.

    -

    Memory, I/O and Misc objects also have their own specific levels and depth.

    -

    -
    -
    -

    The following diagram can help to understand the vocabulary of the relationships by showing the example of a machine with two dual core packages (with no hardware threads); thus, a topology with 5 levels. Each box with rounded corner corresponds to one hwloc_obj_t, containing the values of the different integer fields (depth, logical_index, etc.), and arrows show to which other hwloc_obj_t pointers point to (first_child, parent, etc.).

    -

    The topology always starts with a Machine object as root (depth 0) and ends with PU objects at the bottom (depth 4 here).

    -

    Objects of the same level (cousins) are listed in red boxes and linked with red arrows. Children of the same parent (siblings) are linked with blue arrows.

    -

    The L2 cache of the last core is intentionally missing to show how asymmetric topologies are handled. See What happens if my topology is asymmetric? for more information about such strange topologies.

    -
    - -
    -

    It should be noted that for PU objects, the logical index – as computed linearly by hwloc – is not the same as the OS index.

    -

    The NUMA node is on the side because it is not part of the main tree but rather attached to the object that corresponds to its locality (the entire machine here, hence the root object). It is attached as a Memory child (in green) and has a virtual depth (negative). It could also have siblings if there were multiple local NUMA nodes, or cousins if other NUMA nodes were attached somewhere else in the machine.

    -

    I/O or Misc objects could be attached in a similar manner.

    -
    -
    - - - - - - -
    -
    -
    -
    Command-Line Tools
    -
    -
    -

    -

    -

    -

    hwloc comes with an extensive C programming interface and several command line utilities. Each of them is fully documented in its own manual page; the following is a summary of the available command line tools.

    -

    -

    -

    -

    -lstopo and lstopo-no-graphics

    -

    lstopo (also known as hwloc-ls) displays the hierarchical topology map of the current system. The output may be graphical, ascii-art or textual, and can also be exported to numerous file formats such as PDF, PNG, XML, and others. Advanced graphical outputs require the "Cairo" development package (usually cairo-devel or libcairo2-dev).

    -

    lstopo and lstopo-no-graphics accept the same command-line options. However, graphical outputs are only available in lstopo. Textual outputs (those that do not depend on heavy external libraries such as Cairo) are supported in both lstopo and lstopo-no-graphics.

    -

    This command can also display the processes currently bound to a part of the machine (via the --ps option).

    -

    Note that lstopo can read XML files and/or alternate chroot filesystems and display topological maps representing those systems (e.g., use lstopo to output an XML file on one system, and then use lstopo to read in that XML file and display it on a different system).

    -

    -

    -

    -

    -hwloc-bind

    -

    hwloc-bind binds processes to specific hardware objects through a flexible syntax. A simple example is binding an executable to specific cores (or packages or bitmaps or ...). The hwloc-bind(1) man page provides much more detail on what is possible.

    -

    hwloc-bind can also be used to retrieve the current process' binding, or retrieve the last CPU(s) where a process ran, or operate on memory binding.

    -

    Just like hwloc-calc, the input locations given to hwloc-bind may be either objects or cpusets (bitmaps as reported by hwloc-calc or hwloc-distrib).

    -

    -

    -

    -

    -hwloc-calc

    -

    hwloc-calc is hwloc's Swiss Army Knife command-line tool for converting things. The input may be either objects or cpusets (bitmaps as reported by another hwloc-calc instance or by hwloc-distrib), that may be combined by addition, intersection or subtraction. The output may be expressed as:

      -
    • -a cpuset bitmap: This compact opaque representation of objects is useful for shell scripts etc. It may passed to hwloc command-line tools such as hwloc-calc or hwloc-bind, or to hwloc command-line options such as lstopo --restrict.
      • -
    • -a nodeset bitmap: Another opaque representation that represents memory locality more precisely, especially if some NUMA nodes are CPU less or if multiple NUMA nodes are local to the same CPUs.
      • -
    • -the amount of the equivalent hwloc objects from a specific type, or the list of their indexes. This is useful for iterating over all similar objects (for instance all cores) within a given part of a platform.
      • -
    • -a hierarchical description of objects, for instance a thread index within a core within a package. This gives a better view of the actual location of an object.
      • -
    -

    Moreover, input and/or output may be use either physical/OS object indexes or as hwloc's logical object indexes. It eases cooperation with external tools such as taskset or numactl by exporting hwloc specifications into list of processor or NUMA node physical indexes. See also Should I use logical or physical/OS indexes? and how?.

    -

    -

    -

    -

    -hwloc-info

    -

    hwloc-info dumps information about the given objects, as well as all its specific attributes. It is intended to be used with tools such as grep for filtering certain attribute lines. When no object is specified, or when --topology is passed, hwloc-info prints a summary of the topology. When --support is passed, hwloc-info lists the supported features for the topology.

    -

    -

    -

    -

    -hwloc-distrib

    -

    hwloc-distrib generates a set of cpuset bitmaps that are uniformly distributed across the machine for the given number of processes. These strings may be used with hwloc-bind to run processes to maximize their memory bandwidth by properly distributing them across the machine.

    -

    -

    -

    -

    -hwloc-ps

    -

    hwloc-ps is a tool to display the bindings of processes that are currently running on the local machine. By default, hwloc-ps only lists processes that are bound; unbound process (and Linux kernel threads) are not displayed.

    -

    -

    -

    -

    -hwloc-annotate

    -

    hwloc-annotate may modify object (and topology) attributes such as string information (see Custom string infos for details) or Misc children objects. It may also add distances, memory attributes, etc. to the topology. It reads an input topology from a XML file and outputs the annotated topology as another XML file.

    -

    -

    -

    -

    -hwloc-diff, hwloc-patch and hwloc-compress-dir

    -

    hwloc-diff computes the difference between two topologies and outputs it to another XML file.

    -

    hwloc-patch reads such a difference file and applies to another topology.

    -

    hwloc-compress-dir compresses an entire directory of XML files by using hwloc-diff to save the differences between topologies instead of entire topologies.

    -

    -

    -

    -

    -hwloc-dump-hwdata

    -

    hwloc-dump-hwdata is a Linux and x86-specific tool that dumps (during boot, privileged) some topology and locality information from raw hardware files (SMBIOS and ACPI tables) to human-readable and world-accessible files that the hwloc library will later reuse.

    -

    Currently only used on Intel Xeon Phi processor platforms. See Why do I need hwloc-dump-hwdata for memory on Intel Xeon Phi processor?.

    -

    See HWLOC_DUMPED_HWDATA_DIR in Environment Variables for details about the location of dumped files.

    -

    -

    -

    -

    -hwloc-gather-topology and hwloc-gather-cpuid

    -

    hwloc-gather-topology is a Linux-specific tool that saves the relevant topology files of the current machine into a tarball (and the corresponding lstopo outputs).

    -

    hwloc-gather-cpuid is a x86-specific tool that dumps the result of CPUID instructions on the current machine into a directory.

    -

    The output of hwloc-gather-cpuid is included in the tarball saved by hwloc-gather-topology when running on Linux/x86.

    -

    These files may be used later (possibly offline) for simulating or debugging a machine without actually running on it.

    -
    -
    - - - - - - -
    -
    -
    -
    Environment Variables
    -
    -
    -

    -

    -

    -

    The behavior of the hwloc library and tools may be tuned thanks to the following environment variables.

    -
    -
    HWLOC_XMLFILE=/path/to/file.xml
    -

    enforces the discovery from the given XML file as if hwloc_topology_set_xml() had been called. This file may have been generated earlier with lstopo file.xml. For convenience, this backend provides empty binding hooks which just return success. To have hwloc still actually call OS-specific hooks, HWLOC_THISSYSTEM should be set 1 in the environment too, to assert that the loaded file is really the underlying system. See also Importing and exporting topologies from/to XML files.

    -

    -
    -
    HWLOC_SYNTHETIC=synthetic_description
    -

    enforces the discovery through a synthetic description string as if hwloc_topology_set_synthetic() had been called. For convenience, this backend provides empty binding hooks which just return success. See also Synthetic topologies.

    -

    -
    -
    HWLOC_XML_VERBOSE=1
    -
    -
    HWLOC_SYNTHETIC_VERBOSE=1
    -

    enables verbose messages in the XML or synthetic topology backends. hwloc XML backends (see Importing and exporting topologies from/to XML files) can emit some error messages to the error output stream. Enabling these verbose messages within hwloc can be useful for understanding failures to parse input XML topologies. Similarly, enabling verbose messages in the synthetic topology backend can help understand why the description string is invalid. See also Synthetic topologies.

    -

    -
    -
    HWLOC_THISSYSTEM=1
    -

    enforces the return value of hwloc_topology_is_thissystem(), as if HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM was set with hwloc_topology_set_flags(). It means that it makes hwloc assume that the selected backend provides the topology for the system on which we are running, even if it is not the OS-specific backend but the XML backend for instance. This means making the binding functions actually call the OS-specific system calls and really do binding, while the XML backend would otherwise provide empty hooks just returning success. This can be used for efficiency reasons to first detect the topology once, save it to a XML file, and quickly reload it later through the XML backend, but still having binding functions actually do bind. This also enables support for the variable HWLOC_THISSYSTEM_ALLOWED_RESOURCES.

    -

    -
    -
    HWLOC_THISSYSTEM_ALLOWED_RESOURCES=1
    -

    Get the set of allowed resources from the native operating system even if the topology was loaded from XML or synthetic description, as if HWLOC_TOPOLOGY_FLAG_THISSYSTEM_ALLOWED_RESOURCES was set with hwloc_topology_set_flags(). This variable requires the topology to match the current system (see the variable HWLOC_THISSYSTEM). This is useful when the topology is not loaded directly from the local machine (e.g. for performance reason) and it comes with all resources, but the running process is restricted to only a part of the machine (for instance because of Linux Cgroup/Cpuset).

    -

    -
    -
    HWLOC_ALLOW=all
    -

    Totally ignore administrative restrictions such as Linux Cgroups and consider all resources (PUs and NUMA nodes) as allowed. This is different from setting HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED which gathers all resources but marks the unavailable ones as disallowed.

    -

    -
    -
    HWLOC_HIDE_ERRORS=1
    -

    enables or disables verbose reporting of errors. The hwloc library may issue warnings to the standard error stream when it detects a problem during topology discovery, for instance if the operating system (or user) gives contradictory topology information.

    -

    By default (1), hwloc only shows critical errors such as invalid hardware topology information or invalid configuration. If set to 0 (default in lstopo), more errors are displayed, for instance a failure to initialize CUDA or NVML. If set to 2, no hwloc error messages are shown.

    -

    Note that additional verbose messages may be enabled with other variables such as HWLOC_GROUPING_VERBOSE.

    -

    -
    -
    HWLOC_USE_NUMA_DISTANCES=7
    -

    enables or disables the use of NUMA distances. NUMA distances and memory target/initiator information may be used to improve the locality of NUMA nodes, especially CPU-less nodes. Bits in the value of this environment variable enable different features: Bit 0 enables the gathering of NUMA distances from the operating system. Bit 1 further enables the use of NUMA distances to improve the locality of CPU-less nodes. Bit 2 enables the use of target/initiator information.

    -

    -
    -
    HWLOC_GROUPING=1
    -

    enables or disables objects grouping based on distances. By default, hwloc uses distance matrices between objects (either read from the OS or given by the user) to find groups of close objects. These groups are described by adding intermediate Group objects in the topology. Setting this environment variable to 0 will disable this grouping. This variable supersedes the obsolete HWLOC_IGNORE_DISTANCES variable.

    -

    -
    -
    HWLOC_GROUPING_ACCURACY=0.05
    -

    relaxes distance comparison during grouping. By default, objects may be grouped if their distances form a minimal distance graph. When setting this variable to 0.02, and when HWLOC_DISTANCES_ADD_FLAG_GROUP_INACCURATE is given, these distances do not have to be strictly equal anymore, they may just be equal with a 2% error. If set to try instead of a numerical value, hwloc will try to group with perfect accuracy (0, the default), then with 0.01, 0.02, 0.05 and finally 0.1. Numbers given in this environment variable should always use a dot as a decimal mark (for instance 0.01 instead of 0,01).

    -

    -
    -
    HWLOC_GROUPING_VERBOSE=0
    -

    enables or disables some verbose messages during grouping. If this variable is set to 1, some debug messages will be displayed during distance-based grouping of objects even if debug was not specific at configure time. This is useful when trying to find an interesting distance grouping accuracy.

    -

    -
    -
    HWLOC_CPUKINDS_RANKING=default
    -

    change the ranking policy for CPU kinds. hwloc tries to rank CPU kinds that are energy efficiency first, and then CPUs that are rather high-performance and power hungry.
    - By default, if available, the OS-provided efficiency is used for ranking. Otherwise, the frequency and/or core types are used when available.
    - This environment variable may be set to coretype+frequency, coretype+frequency_strict, coretype, frequency, frequency_base, frequency_max, forced_efficiency, no_forced_efficiency, default, or none.

    -

    -
    -
    HWLOC_CPUKINDS_MAXFREQ=adjust=10
    -

    change the use of the max frequency in the Linux backend. hwloc tries to read the base and max frequencies of each core on Linux. Some hardware features such as Intel Turbo Boost Max 3.0 make some cores report slightly higher max frequencies than others in the same CPU package. Despite having slightly different frequencies, these cores are considered identical instead of exposing an hybrid CPU. Hence, by default, hwloc uniformizes the max frequencies of cores that have the same base frequency (higher values are downgraded by up to 10%).

    -

    If this environment variable is set to adjust=X, the 10% threshold is replaced with X. If set to 1, max frequencies are not adjusted anymore, some homogeneous processors may appear hybrid because of this. If set to 0, max frequencies are entirely ignored.

    -

    -
    -
    HWLOC_PCI_LOCALITY=<domain/bus> <cpuset>;...
    -
    -
    HWLOC_PCI_LOCALITY=/path/to/pci/locality/file
    -

    changes the locality of I/O devices behing the specified PCI buses. If no I/O locality information is available or if the BIOS reports incorrect information, it is possible to move a I/O device tree (OS and/or PCI devices with optional bridges) near a custom set of processors.
    - Localities are given either inside the environment variable itself, or in the pointed file. They may be separated either by semi-colons or by line-breaks. Invalid localities are silently ignored, hence it is possible to insert comments between actual localities.
    - Each locality contains a domain/bus specification (in hexadecimal numbers as usual) followed by a whitespace and a cpuset:

      -
    • -0001 <cpuset> specifies the locality of all buses in PCI domain 0000.
      • -
    • -0000:0f <cpuset> specifies only PCI bus 0f in domain 0000.
      • -
    • -0002:04-0a <cpuset> specifies a range of buses (from 04 to 0a) within domain 0002.
      • -
    -

    Domain/bus specifications should usually match entire hierarchies of buses behind a bridge (including primary, secondary and subordinate buses). For instance, if hostbridge 0000:00 is above other bridges/switches with buses 0000:01 to 0000:09, the variable should be HWLOC_PCI_LOCALITY="0000:00-09 <cpuset>". It supersedes the old HWLOC_PCI_0000_00_LOCALCPUS=<cpuset> which only works when hostbridges exist in the topology.
    - If the variable is defined to empty or invalid, no forced PCI locality is applied but hwloc's internal automatic locality quirks are disabled, which means the exact PCI locality reported by the platform is used.

    -

    -
    -
    HWLOC_X86_TOPOEXT_NUMANODES=0
    -

    use AMD topoext CPUID leaf in the x86 backend to detect NUMA nodes. When using the x86 backend, setting this variable to 1 enables the building of NUMA nodes from AMD processor CPUID instructions. However this strategy does not always reflect BIOS configuration such as NUMA interleaving. And node indexes may be different from those of the operating system. Hence this should only be used when OS backends are wrong and the user is sure that CPUID returns correct NUMA information.

    -

    -
    -
    HWLOC_KEEP_NVIDIA_GPU_NUMA_NODES=0
    -

    show or hide NUMA nodes that correspond to NVIDIA GPU memory. By default they are ignored to avoid interleaved memory being allocated on GPU by mistake. Setting this environment variable to 1 exposes these NUMA nodes. They may be recognized by the GPUMemory subtype. They also have a PCIBusID info attribute to identify the corresponding GPU.

    -

    -
    -
    HWLOC_KNL_MSCACHE_L3=0
    -

    Expose the KNL MCDRAM in cache mode as a Memory-side Cache instead of a L3. hwloc releases prior to 2.1 exposed the MCDRAM cache as a CPU-side L3 cache. Now that Memory-side caches are supported by hwloc, it is still exposed as a L3 by default to avoid breaking existing applications. Setting this environment variable to 1 will expose it as a proper Memory-side cache.

    -

    -
    -
    HWLOC_WINDOWS_PROCESSOR_GROUP_OBJS=0
    -

    Expose Windows processor groups as hwloc Group objects. By default, these groups are disabled because they may be incompatible with the hierarchy of resources that hwloc builds (leading to warnings). Setting this variable to 1 reenables the addition of these groups to the topology.

    -

    This variable does not impact the querying of Windows processor groups using the dedicated API in hwloc/windows.h, this feature is always supported.

    -

    -
    -
    HWLOC_ANNOTATE_GLOBAL_COMPONENTS=0
    -

    Allow components to annotate the topology even if they are usually excluded by global components by default. Setting this variable to 1 and also setting HWLOC_COMPONENTS=xml,pci,stop enables the addition of PCI vendor and model info attributes to a XML topology that was generated without those names (if pciaccess was missing).

    -

    -
    -
    HWLOC_FSROOT=/path/to/linux/filesystem-root/
    -

    switches to reading the topology from the specified Linux filesystem root instead of the main file-system root. This directory may have been saved previously from another machine with hwloc-gather-topology.
    - One should likely also set HWLOC_COMPONENTS=linux,stop so that non-Linux backends are disabled (the -i option of command-line tools takes care of both).
    - Not using the main file-system root causes hwloc_topology_is_thissystem() to return 0. For convenience, this backend provides empty binding hooks which just return success. To have hwloc still actually call OS-specific hooks, HWLOC_THISSYSTEM should be set 1 in the environment too, to assert that the loaded file is really the underlying system.

    -

    -
    -
    HWLOC_CPUID_PATH=/path/to/cpuid/
    -

    forces the x86 backend to read dumped CPUIDs from the given directory instead of executing actual x86 CPUID instructions. This directory may have been saved previously from another machine with hwloc-gather-cpuid.
    - One should likely also set HWLOC_COMPONENTS=x86,stop so that non-x86 backends are disabled (the -i option of command-line tools takes care of both).
    - It causes hwloc_topology_is_thissystem() to return 0. For convenience, this backend provides empty binding hooks which just return success. To have hwloc still actually call OS-specific hooks, HWLOC_THISSYSTEM should be set 1 in the environment too, to assert that the loaded CPUID dump is really the underlying system.

    -

    -
    -
    HWLOC_DUMPED_HWDATA_DIR=/path/to/dumped/files/
    -

    loads files dumped by hwloc-dump-hwdata (on Linux) from the given directory. The default dump/load directory is configured during build based on --runstatedir, --localstatedir, and --prefix options. It usually points to /var/run/hwloc/ in Linux distribution packages, but it may also point to $prefix/var/run/hwloc/ when manually installing and only specifying --prefix.

    -

    -
    -
    HWLOC_COMPONENTS=list,of,components
    -

    forces a list of components to enable or disable. Enable or disable the given comma-separated list of components (if they do not conflict with each other). Component names prefixed with - are disabled (a single phase may also be disabled).

    -

    Once the end of the list is reached, hwloc falls back to enabling the remaining components (sorted by priority) that do not conflict with the already enabled ones, and unless explicitly disabled in the list. If stop is met, the enabling loop immediately stops, no more component is enabled.

    -

    If xml or synthetic components are selected, the corresponding XML filename or synthetic description string should be pass in HWLOC_XMLFILE or HWLOC_SYNTHETIC respectively.

    -

    Since this variable is the low-level and more generic way to select components, it takes precedence over environment variables for selecting components.

    -

    If the variable is set to an empty string (or set to a single comma), no specific component is loaded first, all components are loaded in priority order.

    -

    See Selecting which components to use for details.

    -

    -
    -
    HWLOC_COMPONENTS_VERBOSE=1
    -

    displays verbose information about components. Display messages when components are registered or enabled. This is the recommended way to list the available components with their priority (all of them are registered at startup).

    -

    -
    -
    HWLOC_PLUGINS_PATH=/path/to/hwloc/plugins/:...
    -

    changes the default search directory for plugins. By default, $libdir/hwloc is used. The variable may contain several colon-separated directories.

    -

    -
    -
    HWLOC_PLUGINS_VERBOSE=1
    -

    displays verbose information about plugins. List which directories are scanned, which files are loaded, and which components are successfully loaded.

    -

    -
    -
    HWLOC_PLUGINS_BLACKLIST=filename1,filename2,...
    -

    prevents plugins from being loaded if their filename (without path) is listed. Plugin filenames may be found in verbose messages outputted when HWLOC_PLUGINS_VERBOSE=1.

    -

    -
    -
    HWLOC_DEBUG_VERBOSE=0
    -

    disables all verbose messages that are enabled by default when –enable-debug is passed to configure. When set to more than 1, even more verbose messages are displayed. The default is 1.

    -

    -
    -
    -
    -
    - - - - - - -
    -
    -
    -
    CPU and Memory Binding Overview
    -
    -
    -

    -

    -

    -

    Some operating systems do not systematically provide separate functions for CPU and memory binding. This means that CPU binding functions may have have effects on the memory binding policy. Likewise, changing the memory binding policy may change the CPU binding of the current thread. This is often not a problem for applications, so by default hwloc will make use of these functions when they provide better binding support.

    -

    If the application does not want the CPU binding to change when changing the memory policy, it needs to use the HWLOC_MEMBIND_NOCPUBIND flag to prevent hwloc from using OS functions which would change the CPU binding. Additionally, HWLOC_CPUBIND_NOMEMBIND can be passed to CPU binding function to prevent hwloc from using OS functions would change the memory binding policy. Of course, using these flags will reduce hwloc's overall support for binding, so their use is discouraged.

    -

    One can avoid using these flags but still closely control both memory and CPU binding by allocating memory, touching each page in the allocated memory, and then changing the CPU binding. The already-really-allocated memory will then be "locked" to physical memory and will not be migrated. Thus, even if the memory binding policy gets changed by the CPU binding order, the already-allocated memory will not change with it. When binding and allocating further memory, the CPU binding should be performed again in case the memory binding altered the previously-selected CPU binding.

    -

    Not all operating systems support the notion of a "current" memory binding policy for the current process, but such operating systems often still provide a way to allocate data on a given node set. Conversely, some operating systems support the notion of a "current" memory binding policy and do not permit allocating data on a specific node set without changing the current policy and allocate the data. To provide the most powerful coverage of these facilities, hwloc provides:

    -
      -
    • -functions that set/get the current memory binding policies (if supported): hwloc_set/get_membind() and hwloc_set/get_proc_membind()
      • -
    • -a function that allocates memory bound to specific node set without changing the current memory binding policy (if supported): hwloc_alloc_membind().
      • -
    • -a helper which, if needed, changes the current memory binding policy of the process in order to obtain memory binding: hwloc_alloc_membind_policy().
      • -
    -

    An application can thus use the two first sets of functions if it wants to manage separately the global process binding policy and directed allocation, or use the third set of functions if it does not care about the process memory binding policy.

    -

    See CPU binding and Memory binding for hwloc's API functions regarding CPU and memory binding, respectively. There are some examples under doc/examples/ in the source tree.

    -
    -
    - - - - - - -
    -
    -
    -
    I/O Devices
    -
    -
    -

    -

    -

    -

    hwloc usually manipulates processing units and memory but it can also discover I/O devices and report their locality as well. This is useful for placing I/O intensive applications on cores near the I/O devices they use, or for gathering information about all platform components.

    -

    -

    -

    -

    -Enabling and requirements

    -

    I/O discovery is disabled by default (except in lstopo) for performance reasons. It can be enabled by changing the filtering of I/O object types to HWLOC_TYPE_FILTER_KEEP_IMPORTANT or HWLOC_TYPE_FILTER_KEEP_ALL before loading the topology, for instance with hwloc_topology_set_io_types_filter().

    -

    Note that I/O discovery requires significant help from the operating system. The pciaccess library (the development package is usually libpciaccess-devel or libpciaccess-dev) is needed to fully detect PCI devices and bridges/switches. On Linux, PCI discovery may still be performed even if libpciaccess cannot be used. But it misses PCI device names. Moreover, some operating systems require privileges for probing PCI devices, see Does hwloc require privileged access? for details.

    -

    The actual locality of I/O devices is only currently detected on Linux. Other operating system will just report I/O devices as being attached to the topology root object.

    -

    -

    -

    -

    -I/O objects

    -

    When I/O discovery is enabled and supported, some additional objects are added to the topology. The corresponding I/O object types are:

    -

    Any of these types may be filtered individually with hwloc_topology_set_type_filter().

    -

    hwloc tries to attach these new objects to normal objects (usually NUMA nodes) to match their actual physical location. For instance, if a I/O hub (or root complex) is physically connected to a package, the corresponding hwloc bridge object (and its PCI bridges and devices children) is inserted as a child of the corresponding hwloc Package object. These children are not in the normal children list but rather in the I/O-specific children list.

    -

    I/O objects also have neither CPU sets nor node sets (NULL pointers) because they are not directly usable by the user applications for binding. Moreover I/O hierarchies may be highly complex (asymmetric trees of bridges). So I/O objects are placed in specific levels with custom depths. Their lists may still be traversed with regular helpers such as hwloc_get_next_obj_by_type(). However, hwloc offers some dedicated helpers such as hwloc_get_next_pcidev() and hwloc_get_next_osdev() for convenience (see Finding I/O objects).

    -

    -

    -

    -

    -OS devices

    -

    Although each PCI device is uniquely identified by its bus ID (e.g. 0000:01:02.3), a user-space application can hardly find out which PCI device it is actually using. Applications rather use software handles (such as the eth0 network interface, the sda hard drive, or the mlx4_0 OpenFabrics HCA). Therefore hwloc tries to add software devices (HWLOC_OBJ_OS_DEVICE, also known as OS devices).

    -

    OS devices may be attached below PCI devices, but they may also be attached directly to normal objects. Indeed some OS devices are not related to PCI. For instance, NVDIMM block devices (such as pmem0s on Linux) are directly attached near their NUMA node (I/O child of the parent whose memory child is the NUMA node). Also, if hwloc could not discover PCI for some reason, PCI-related OS devices may also be attached directly to normal objects.

    -

    Finally, OS subdevices may be exposed as OS devices children of another OS device. This is the case of LevelZero subdevices for instance.

    -

    hwloc first tries to discover OS devices from the operating system, e.g. eth0, sda or mlx4_0. However, this ability is currently only available on Linux for some classes of devices.

    -

    hwloc then tries to discover software devices through additional I/O components using external libraries. For instance proprietary graphics drivers do not expose any named OS device, but hwloc may still create one OS object per software handle when supported. For instance the opencl and cuda components may add some opencl0d0 and cuda0 OS device objects.

    -

    Here is a list of OS device objects commonly created by hwloc components when I/O discovery is enabled and supported.

    -
      -
    • -Hard disks or non-volatile memory devices (HWLOC_OBJ_OSDEV_BLOCK)
        -
      • -sda or dax2.0 (Linux component)
        • -
      -
      • -
    • -Network interfaces (HWLOC_OBJ_OSDEV_NETWORK)
        -
      • -eth0, wlan0, ib0 (Linux component)
        • -
      • -hsn0 with "Slingshot" subtype for HPE Cray HSNs (Linux component).
        • -
      -
      • -
    • -OpenFabrics (InfiniBand, Omni-Path, usNIC, etc) HCAs (HWLOC_OBJ_OSDEV_OPENFABRICS)
        -
      • -mlx5_0, hfi1_0, qib0, usnic_0 (Linux component)
        • -
      • -bxi0 with "BXI" subtype for Atos/Bull BXI HCAs (Linux component) even if those are not really OpenFabrics.
        • -
      -
      • -
    • -GPUs (HWLOC_OBJ_OSDEV_GPU)
        -
      • -rsmi0 for the first RSMI device ("RSMI" subtype, from the RSMI component, using the AMD ROCm SMI library)
        • -
      • -nvml0 for the first NVML device ("NVML" subtype, from the NVML component, using the NVIDIA Management Library)
        • -
      • -:0.0 for the first display ("Display" subtype, from the GL component, using the NV-CONTROL X extension library, NVCtrl)
        • -
      • -card0 and renderD128 for DRM device files (from the Linux component, filtered-out by default because considered non-important)
        • -
      -
      • -
    • -Co-Processors (HWLOC_OBJ_OSDEV_COPROC)
        -
      • -opencl0d0 for the first device of the first OpenCL platform, opencl1d3 for the fourth device of the second OpenCL platform ("OpenCL" subtype, from the OpenCL component)
        • -
      • -ze0 for the first Level Zero device ("LevelZero" subtype, from the levelzero component, using the oneAPI Level Zero library), and ze0.1 for its second subdevice (if any).
        • -
      • -cuda0 for the first NVIDIA CUDA device ("CUDA" subtype, from the CUDA component, using the NVIDIA CUDA Library)
        • -
      • -ve0 for the first NEC Vector Engine device ("VectorEngine" subtype, from the Linux component)
        • -
      -
      • -
    • -DMA engine channel (HWLOC_OBJ_OSDEV_DMA) -
      • -
    -

    Note that some PCI devices may contain multiple software devices (see the example below).

    -

    See also Interoperability With Other Software for managing these devices without considering them as hwloc objects.

    -

    -

    -

    -

    -PCI devices and bridges

    -

    A PCI hierarchy is usually organized as follows: A hostbridge object ( HWLOC_OBJ_BRIDGE object with upstream type Host and downstream type PCI) is attached below a normal object (usually the entire machine or a NUMA node). There may be multiple hostbridges in the machine, attached to different places, but all PCI devices are below one of them (unless the Bridge object type is filtered-out).

    -

    Each hostbridge contains one or several children, either other bridges (usually PCI to PCI switches) or PCI devices (HWLOC_OBJ_PCI_DEVICE). The number of bridges between the hostbridge and a PCI device depends on the machine.

    -

    -

    -

    -

    -Consulting I/O devices and binding

    -

    I/O devices may be consulted by traversing the topology manually (with usual routines such as hwloc_get_obj_by_type()) or by using dedicated helpers (such as hwloc_get_pcidev_by_busid(), see Finding I/O objects).

    -

    I/O objects do not actually contain any locality information because their CPU sets and node sets are NULL. Their locality must be retrieved by walking up the object tree (through the parent link) until a non-I/O object is found (see hwloc_get_non_io_ancestor_obj()). This normal object should have non-NULL CPU sets and node sets which describe the processing units and memory that are immediately close to the I/O device. For instance the path from a OS device to its locality may go across a PCI device parent, one or several bridges, up to a Package node with the same locality.

    -

    Command-line tools are also aware of I/O devices. lstopo displays the interesting ones by default (passing --no-io disables it).

    -

    hwloc-calc and hwloc-bind may manipulate I/O devices specified by PCI bus ID or by OS device name.

      -
    • -pci=0000:02:03.0 is replaced by the set of CPUs that are close to the PCI device whose bus ID is given.
      • -
    • -os=eth0 is replaced by CPUs that are close to the I/O device whose software handle is called eth0.
      • -
    -

    This enables easy binding of I/O-intensive applications near the device they use.

    -

    -

    -

    -

    -Examples

    -

    The following picture shows a dual-package dual-core host whose PCI bus is connected to the first package and NUMA node.

    -
    - -
    -

    Six interesting PCI devices were discovered. However, hwloc found some corresponding software devices (eth0, eth1, sda, mlx4_0, ib0, and ib1) for only four of these physical devices. The other ones (PCI 102b:0532 and PCI 8086:3a20) are an unused IDE controller (no disk attached) and a graphic card (no corresponding software device reported to the user by the operating system).

    -

    On the contrary, it should be noted that three different software devices were found for the last PCI device (PCI 15b3:634a). Indeed this OpenFabrics HCA PCI device object contains one one OpenFabrics software device (mlx4_0) and two virtual network interface software devices (ib0 and ib1).

    -

    Here is the corresponding textual output:

    -
    Machine (24GB total)
-  Package L#0
-    NUMANode L#0 (P#0 12GB)
-    L3 L#0 (8192KB)
-      L2 L#0 (256KB) + L1 L#0 (32KB) + Core L#0 + PU L#0 (P#0)
-      L2 L#1 (256KB) + L1 L#1 (32KB) + Core L#1 + PU L#1 (P#2)
-    HostBridge
-      PCIBridge
-        PCI 01:00.0 (Ethernet)
-          Net "eth0"
-        PCI 01:00.1 (Ethernet)
-          Net "eth1"
-      PCIBridge
-        PCI 03:00.0 (RAID)
-          Block "sda"
-      PCIBridge
-        PCI 04:03.0 (VGA)
-      PCI 00:1f.2 (IDE)
-      PCI 51:00.0 (InfiniBand)
-        Net "ib0"
-        Net "ib1"
-        Net "mlx4_0"
-  Package L#1
-    NUMANode L#1 (P#1 12GB)
-    L3 L#1 (8192KB)
-      L2 L#2 (256KB) + L1 L#2 (32KB) + Core L#2 + PU L#2 (P#1)
-      L2 L#3 (256KB) + L1 L#3 (32KB) + Core L#3 + PU L#3 (P#3)
-
    -
    - - - - - - -
    -
    -
    -
    Miscellaneous objects
    -
    -
    -

    -

    -

    -

    hwloc topologies may be annotated with Misc objects (of type HWLOC_OBJ_MISC) either automatically or by the user. This is a flexible way to annotate topologies with large sets of information since Misc objects may be inserted anywhere in the topology (to annotate specific objects or parts of the topology), even below other Misc objects, and each of them may contain multiple attributes (see also How do I annotate the topology with private notes?).

    -

    These Misc objects may have a subtype field to replace Misc with something else in the lstopo output.

    -

    -

    -

    -

    -Misc objects added by hwloc

    -

    hwloc only uses Misc objects when other object types are not sufficient, and when the Misc object type is not filtered-out anymore. This currently includes:

      -
    • -Memory modules (DIMMs), on Linux when privileged and when dmi-sysfs is supported by the kernel. These objects have a subtype field of value MemoryModule. They are currently always attached to the root object. Their attributes describe the DIMM vendor, model, etc. lstopo -v displays them as:
      Misc(MemoryModule) (P#1 DeviceLocation="Bottom-Slot 2(right)" BankLocation="BANK 2" Vendor=Elpida SerialNumber=21733667 AssetTag=9876543210 PartNumber="EBJ81UG8EFU0-GN-F ")
      -
      • -
    • -Displaying process binding in lstopo --top. These objects have a subtype field of value Process and a name attribute made of their PID and program name. They are attached below the object they are bound to. The textual lstopo displays them as:
      PU L#0 (P#0)
      -
      Misc(Process) 4445 myprogram
      -
      • -
    -

    -

    -

    -

    -Annotating topologies with Misc objects

    -

    The user may annotate hwloc topologies with its own Misc objects. This can be achieved with hwloc_topology_insert_misc_object() as well as hwloc-annotate command-line tool.

    -
    -
    - - - - - - -
    -
    -
    -
    Object attributes
    -
    -
    -

    -

    -

    -

    -Normal attributes

    -

    hwloc objects have many generic attributes in the hwloc_obj structure, for instance their logical_index or os_index (see Should I use logical or physical/OS indexes? and how?), depth or name.

    -

    The kind of object is first described by the obj->type generic attribute (an integer). OS devices also have a specific obj->attr->osdev.type integer for distinguishing between NICs, GPUs, etc.

    -

    Objects may also have an optional obj->subtype pointing to a better description string (displayed by lstopo either in place or after the main obj->type attribute):

      -
    • -NUMA nodes: subtype DRAM (for usual main memory), HBM (high-bandwidth memory), SPM (specific-purpose memory, usually reserved for some custom applications), NVM (non-volatile memory when used as main memory), MCDRAM (on KNL) or GPUMemory (on POWER architecture with NVIDIA GPU memory shared over NVLink).
      • -
    • -Groups: subtype Cluster, Module, Tile, Compute Unit, Book or Drawer for different architecture-specific groups of CPUs (see also What are these Group objects in my topology?).
      • -
    • -OS devices (see also OS devices):
        -
      • -Co-processor: subtype OpenCL, LevelZero, CUDA, or VectorEngine.
        • -
      • -GPU: subtype RSMI (AMD GPU) or NVML (NVIDIA GPU).
        • -
      • -OpenFabrics: subtype BXI (Bull/Atos BXI HCA).
        • -
      • -Network: subtype Slingshot (HPE Cray Slingshot Cassini HSN).
        • -
      • -Block: subtype Disk, NVM (non-volatile memory), SPM (specific-purpose memory), CXLMem (CXL volatile ou persistent memory), Tape, or Removable Media Device.
        • -
      -
      • -
    • -L3 Caches: subtype MemorySideCache when hwloc is configured to expose the KNL MCDRAM in Cache mode as a L3.
      • -
    • -PCI devices: subtype NVSwitch for NVLink switches (see also NVLinkBandwidth in Distances).
      • -
    • -Misc devices: subtype MemoryModule (see also Misc objects added by hwloc)
      • -
    -

    Each object also contains an attr field that, if non NULL, points to a union hwloc_obj_attr_u of type-specific attribute structures. For instance, a L2Cache object obj contains cache-specific information in obj->attr->cache, such as its size and associativity, cache type. See hwloc_obj_attr_u for details.

    -

    -

    -

    -

    -Custom string infos

    -

    Aside os these generic attribute fields, hwloc annotates many objects with string attributes that are made of a key and a value. Each object contains a list of such pairs that may be consulted manually (looking at the object infos array field) or using the hwloc_obj_get_info_by_name(). The user may additionally add new key-value pairs to any object using hwloc_obj_add_info() or the hwloc-annotate program.

    -

    Here is a non-exhaustive list of attributes that may be automatically added by hwloc. Note that these attributes heavily depend on the ability of the operating system to report them. Many of them will therefore be missing on some OS.

    -

    -

    -

    -

    -Hardware Platform Information

    -

    These info attributes are attached to the root object (Machine).

    -
    -
    PlatformName, PlatformModel, PlatformVendor, PlatformBoardID, PlatformRevision,
    -
    -
    SystemVersionRegister, ProcessorVersionRegister (Machine)
    -
    Some POWER/PowerPC-specific attributes describing the platform and processor. Currently only available on Linux. Usually added to Package objects, but can be in Machine instead if hwloc failed to discover any package.
    -
    DMIBoardVendor, DMIBoardName, etc.
    -
    DMI hardware information such as the motherboard and chassis models and vendors, the BIOS revision, etc., as reported by Linux under /sys/class/dmi/id/.
    -
    MemoryMode, ClusterMode
    -

    Intel Xeon Phi processor configuration modes. Available if hwloc-dump-hwdata was used (see Why do I need hwloc-dump-hwdata for memory on Intel Xeon Phi processor?) or if hwloc managed to guess them from the NUMA configuration.

    -

    The memory mode may be Cache, Flat, Hybrid50 (half the MCDRAM is used as a cache) or Hybrid25 (25% of MCDRAM as cache). The cluster mode may be Quadrant, Hemisphere, All2All, SNC2 or SNC4. See doc/examples/get-knl-modes.c in the source directory for an example of retrieving these attributes.

    -
    -
    -

    -

    -

    -

    -Operating System Information

    -

    These info attributes are attached to the root object (Machine).

    -
    -
    OSName, OSRelease, OSVersion, HostName, Architecture
    -
    The operating system name, release, version, the hostname and the architecture name, as reported by the Unix uname command.
    -
    LinuxCgroup
    -
    The name the Linux control group where the calling process is placed.
    -
    WindowsBuildEnvironment
    -
    Either MinGW or Cygwin when one of these environments was used during build.
    -
    -

    -

    -

    -

    -hwloc Information

    -

    Unless specified, these info attributes are attached to the root object (Machine).

    -
    -
    Backend (topology root, or specific object added by that backend)
    -
    The name of the hwloc backend/component that filled the topology. If several components were combined, multiple Backend keys may exist, with different values, for instance x86 and Linux in the root object and CUDA in CUDA OS device objects.
    -
    SyntheticDescription
    -
    The description string that was given to hwloc to build this synthetic topology.
    -
    hwlocVersion
    -
    The version number of the hwloc library that was used to generate the topology. If the topology was loaded from XML, this is not the hwloc version that loaded it, but rather the first hwloc instance that exported the topology to XML earlier.
    -
    ProcessName
    -
    The name of the process that contains the hwloc library that was used to generate the topology. If the topology was from XML, this is not the hwloc process that loaded it, but rather the first process that exported the topology to XML earlier.
    -
    -

    -

    -

    -

    -CPU Information

    -

    These info attributes are attached to Package objects, or to the root object (Machine) if package locality information is missing.

    -
    -
    CPUModel
    -
    The processor model name.
    -
    CPUVendor, CPUModelNumber, CPUFamilyNumber, CPUStepping
    -
    The processor vendor name, model number, family number, and stepping number. Currently available for x86 and Xeon Phi processors on most systems, and for ia64 processors on Linux (except CPUStepping).
    -
    CPURevision
    -
    A POWER/PowerPC-specific general processor revision number, currently only available on Linux.
    -
    CPUType
    -
    A Solaris-specific general processor type name, such as "i86pc".
    -
    -

    -

    -

    -

    -OS Device Information

    -

    These info attributes are attached to OS device objects specified in parentheses.

    -
    -
    Vendor, Model, Revision, SerialNumber, Size, SectorSize (Block OS devices)
    -
    The vendor and model names, revision, serial number, size (in KiB = 1024 bytes) and SectorSize (in bytes).
    -
    LinuxDeviceID (Block OS devices)
    -
    The major/minor device number such as 8:0 of Linux device.
    -
    CXLRAMSize, CXLPMEMSize (CXL Memory Block OS devices)
    -
    The size of the volatile (RAM) or persistent (PMEM) memory in a CXL Type-3 device . Sizes are in KiB (1024 bytes).
    -
    GPUVendor, GPUModel (GPU or Co-Processor OS devices)
    -
    The vendor and model names of the GPU device.
    -
    OpenCLDeviceType, OpenCLPlatformIndex,
    -
    -
    OpenCLPlatformName, OpenCLPlatformDeviceIndex (OpenCL OS devices)
    -
    The type of OpenCL device, the OpenCL platform index and name, and the index of the device within the platform.
    -
    OpenCLComputeUnits, OpenCLGlobalMemorySize (OpenCL OS devices)
    -
    The number of compute units and global memory size of an OpenCL device. Sizes are in KiB (1024 bytes).
    -
    LevelZeroVendor, LevelZeroModel, LevelZeroBrand,
    -
    -
    LevelZeroSerialNumber, LevelZeroBoardNumber (LevelZero OS devices)
    -
    The name of the vendor, device model, brand of a Level Zero device, and its serial and board numbers.
    -
    LevelZeroDriverIndex, LevelZeroDriverDeviceIndex (LevelZero OS devices)
    -
    The index of the Level Zero driver within the list of drivers, and the index of the device within the list of devices managed by this driver.
    -
    LevelZeroUUID (LevelZero OS devices or subdevices)
    -
    The UUID of the device or subdevice.
    -
    LevelZeroSubdevices (LevelZero OS devices)
    -
    The number of subdevices below this OS device.
    -
    LevelZeroSubdeviceID (LevelZero OS subdevices)
    -
    The index of this subdevice within its parent.
    -
    LevelZeroDeviceType (LevelZero OS devices or subdevices)
    -
    A string describing the type of device, for instance "GPU", "CPU", "FPGA", etc.
    -
    LevelZeroNumSlices, LevelZeroNumSubslicesPerSlice,
    -
    -
    LevelZeroNumEUsPerSubslice, LevelZeroNumThreadsPerEU (LevelZero OS devices or subdevices)
    -
    The number of slices in the device, of subslices per slice, of execution units (EU) per subslice, and of threads per EU.
    -
    LevelZeroHBMSize, LevelZeroDDRSize, LevelZeroMemorySize (LevelZero OS devices or subdevices)
    -
    The amount of HBM or DDR memory of a LevelZero device or subdevice. Sizes are in KiB (1024 bytes). If the type of memory could not be determined, the generic name LevelZeroMemorySize is used. For devices that contain subdevices, the amount reported in the root device includes the memories of all its subdevices.
    -
    LevelZeroCQGroups, LevelZeroCQGroup2 (LevelZero OS devices or subdevices)
    -
    The number of completion queue groups, and the description of the third group (as N*0xX where N is the number of queues in the group, and 0xX is the hexadecimal bitmask of ze_command_queue_group_property_flag_t listing properties of those queues).
    -
    AMDUUID, AMDSerial (RSMI GPU OS devices)
    -
    The UUID and serial number of AMD GPUs.
    -
    RSMIVRAMSize, RSMIVisibleVRAMSize, RSMIGTTSize (RSMI GPU OS devices)
    -
    The amount of GPU memory (VRAM), of GPU memory that is visible from the host (Visible VRAM), and of system memory that is usable by the GPU (Graphics Translation Table). Sizes are in KiB (1024 bytes).
    -
    XGMIHiveID (RSMI GPU OS devices)
    -
    The ID of the group of GPUs (Hive) interconnected by XGMI links
    -
    XGMIPeers (RSMI GPU OS devices)
    -
    The list of RSMI OS devices that are directly connected to the current device through XGMI links. They are given as a space-separated list of object names, for instance rsmi2 rsmi3.
    -
    NVIDIAUUID, NVIDIASerial (NVML GPU OS devices)
    -
    The UUID and serial number of NVIDIA GPUs.
    -
    CUDAMultiProcessors, CUDACoresPerMP,
    -
    -
    CUDAGlobalMemorySize, CUDAL2CacheSize, CUDASharedMemorySizePerMP (CUDA OS devices)
    -
    The number of shared multiprocessors, the number of cores per multiprocessor, the global memory size, the (global) L2 cache size, and size of the shared memory in each multiprocessor of a CUDA device. Sizes are in KiB (1024 bytes).
    -
    VectorEngineModel, VectorEngineSerialNumber (VectorEngine OS devices)
    -
    The model and serial number of a VectorEngine device.
    -
    VectorEngineCores, VectorEngineMemorySize, VectorEngineLLCSize,
    -
    -
    VectorEngineL2Size, VectorEngineL1dSize, VectorEngineL1iSize (VectorEngine OS devices)
    -
    The number of cores, memory size, and the sizes of the (global) last level cache and of L2, L1d and L1i caches of a VectorEngine device. Sizes are in KiB (1024 bytes).
    -
    VectorEngineNUMAPartitioned (VectorEngine OS devices)
    -
    If this attribute exists, the VectorEngine device is configured in partitioned mode with multiple NUMA nodes.
    -
    Address, Port (Network interface OS devices)
    -
    The MAC address and the port number of a software network interface, such as eth4 on Linux.
    -
    NodeGUID, SysImageGUID, Port1State, Port2LID, Port2LMC, Port3GID1 (OpenFabrics OS devices)
    -
    The node GUID and GUID mask, the state of a port #1 (value is 4 when active), the LID and LID mask count of port #2, and GID #1 of port #3.
    -
    BXIUUID (OpenFabrics BXI OS devices)
    -
    The UUID of an Atos/Bull BXI HCA.
    -
    -

    -

    -

    -

    -Other Object-specific Information

    -

    These info attributes are attached to objects specified in parentheses.

    -
    -
    DAXDevice (NUMA Nodes)
    -
    The name of the Linux DAX device that was used to expose a non-volatile memory region as a volatile NUMA node.
    -
    DAXType (NUMA Nodes or DAX OS devices)
    -
    The type of memory exposed in a Linux DAX device or in the corresponding NUMA node, either "NVM" (non-volatile memory) or "SPM" (specific-purpose memory).
    -
    DAXParent (NUMA Nodes or DAX OS devices)
    -
    A string describing the Linux sysfs hierarchy that exposes the DAX device, for instance containing "hmem1" for specific-purpose memory or "ndbus0" for NVDIMMs.
    -
    -
    -
    PCIBusID (GPUMemory NUMA Nodes)
    -
    The PCI bus ID of the GPU whose memory is exposed in this NUMA node.
    -
    Inclusive (Caches)
    -
    The inclusiveness of a cache (1 if inclusive, 0 otherwise). Currently only available on x86 processors.
    -
    SolarisProcessorGroup (Group)
    -
    The Solaris kstat processor group name that was used to build this Group object.
    -
    PCIVendor, PCIDevice (PCI devices and bridges)
    -
    The vendor and device names of the PCI device.
    -
    PCISlot (PCI devices or Bridges)
    -
    The name/number of the physical slot where the device is plugged. If the physical device contains PCI bridges above the actual PCI device, the attribute may be attached to the highest bridge (i.e. the first object that actually appears below the physical slot).
    -
    Vendor, AssetTag, PartNumber, DeviceLocation, BankLocation (MemoryModule Misc objects)
    -
    Information about memory modules (DIMMs) extracted from SMBIOS.
    -
    -

    -

    -

    -

    -User-Given Information

    -

    Here is a non-exhaustive list of user-provided info attributes that have a special meaning:

    -
    lstopoStyle
    -
    Enforces the style of an object (background and text colors) in the graphical output of lstopo. See CUSTOM COLORS in the lstopo(1) manpage for details.
    -
    -
    -
    - - - - - - -
    -
    -
    -
    Topology Attributes: Distances, Memory Attributes and CPU Kinds
    -
    -
    -

    -

    -

    -

    Besides the hierarchy of objects and individual object attributes (see Object attributes), hwloc may also expose finer information about the hardware organization.

    -

    -

    -

    -

    -Distances

    -

    A machine with 4 CPUs may have identical links between every pairs of CPUs, or those CPUs could also only be connected through a ring. In the ring case, accessing the memory of nearby CPUs is slower than local memory, but it is also faster than accessing the memory of CPU on the opposite side of the ring. These deep details cannot be exposed in the hwloc hierarchy, that is why hwloc also exposes distances.

    -

    Distances are matrices of values between sets of objects, usually latencies or bandwidths. By default, hwloc tries to get a matrix of relative latencies between NUMA nodes when exposed by the hardware.

    -

    In the aforementioned ring case, the matrix could report 10 for latency between a NUMA node and itself, 20 for nearby nodes, and 30 for nodes that are opposites on the ring. Those are theoretical values exposed by hardware vendors (in the System Locality Distance Information Table (SLIT) in the ACPI) rather than physical latencies. They are mostly meant for comparing node relative distances.

    -

    Distances structures currently created by hwloc are:

    -
    NUMALatency (Linux, Solaris, FreeBSD)
    -
    This is the matrix of theoretical latencies described above.
    -
    XGMIBandwidth (RSMI)
    -

    This is the matrix of unidirectional XGMI bandwidths between AMD GPUs (in MB/s). It contains 0 when there is no direct XGMI link between objects. Values on the diagonal are artificially set to very high so that local access always appears faster than remote access.

    -

    GPUs are identified by RSMI OS devices such as "rsmi0". They may be converted into the corresponding OpenCL or PCI devices using hwloc_get_obj_with_same_locality() or the hwloc-annotate tool.

    -

    hwloc_distances_transform() or hwloc-annotate may also be used to transform this matrix into something more convenient, for instance by replacing bandwidths with numbers of links between peers.

    -
    -
    XGMIHops (RSMI)
    -
    This matrix lists the number of XGMI hops between AMD GPUs. It reports 1 when there is a direct link between two distinct GPUs. If there is no XGMI route between them, the value is 0. The number of hops between a GPU and itself (on the diagonal) is 0 as well.
    -
    XeLinkBandwidth (LevelZero)
    -

    This is the matrix of unidirectional XeLink bandwidths between Intel GPUs (in MB/s). It contains 0 when there is no direct XeLink between objects. When there are multiple links, their bandwidth is aggregated.

    -

    Values on the diagonal are artificially set to very high so that local access always appears faster than remote access. This includes bandwidths between a (sub)device and itself, between a subdevice and its parent device, or between two subdevices of the same parent.

    -

    The matrix interconnects all LevelZero devices and subdevices (if any), even if some of them may have no link at all.

    -
    -
    NVLinkBandwidth (NVML)
    -

    This is the matrix of unidirectional NVLink bandwidths between NVIDIA GPUs (in MB/s). It contains 0 when there is no direct NVLink between objects. When there are multiple links, their bandwidth is aggregated. Values on the diagonal are artificially set to very high so that local access always appears faster than remote access.

    -

    On POWER platforms, NVLinks may also connects GPUs to CPUs. On NVIDIA platforms such as DGX-2, a NVSwitch may interconnect GPUs through NVLinks. In these cases, the distances structure is heterogeneous. GPUs always appear first in the matrix (as NVML OS devices such as "nvml0"), and non-GPU objects may appear at the end (Package for POWER processors, PCI device for NVSwitch).

    -

    NVML OS devices may be converted into the corresponding CUDA, OpenCL or PCI devices using hwloc_get_obj_with_same_locality() or the hwloc-annotate tool.

    -

    hwloc_distances_transform() or hwloc-annotate may also be used to transform this matrix into something more convenient, for instance by removing switches or CPU ports, or by replacing bandwidths with numbers of links between peers.

    -

    When a NVSwitch interconnects GPUs, only links between one GPU and different NVSwitch ports are reported. They may be merged into a single switch port with hwloc_distances_transform() or hwloc-annotate. Or a transitive closure may also be applied to report the bandwidth between GPUs across the NVSwitch.

    -
    -
    -

    Users may also specify their own matrices between any set of objects, even if these objects are of different types (e.g. bandwidths between GPUs and CPUs).

    -

    The entire API is located in hwloc/distances.h. See also Retrieve distances between objects, as well as Helpers for consulting distance matrices and Add distances between objects.

    -

    -

    -

    -

    -Memory Attributes

    -

    Machines with heterogeneous memory, for instance high-bandwidth memory (HBM), normal memory (DDR), and/or high-capacity slow memory (such as non-volatile memory DIMMs, NVDIMMs) require applications to allocate buffers in the appropriate target memory depending on performance and capacity needs. Those target nodes may be exposed in the hwloc hierarchy as different memory children but there is a need for performance information to select the appropriate one.

    -

    hwloc memory attributes are designed to expose memory information such as latency, bandwidth, etc. Users may also specify their own attributes and values.

    -

    The memory attributes API is located in hwloc/memattrs.h, see Comparing memory node attributes for finding where to allocate on and Managing memory attributes for details. See also an example in doc/examples/memory-attributes.c in the source tree.

    -

    -

    -

    -

    -CPU Kinds

    -

    Hybrid CPUs may contain different kinds of cores. The CPU kinds API in hwloc/cpukinds.h provides a way to list the sets of PUs in each kind and get some optional information about their hardware characteristics and efficiency.

    -

    If the operating system provides efficiency information (e.g. Windows 10, MacOS X / Darwin and some Linux kernels), it is used to rank hwloc CPU kinds by efficiency. Otherwise, hwloc implements several heuristics based on frequencies and core types (see HWLOC_CPUKINDS_RANKING in Environment Variables).

    -

    The ranking shows energy-efficient CPUs first, and high-performance power-hungry cores last.

    -

    These CPU kinds may be annotated with the following native attributes:

    -
    FrequencyMaxMHz (Linux)
    -
    The maximal operating frequency of the core, as reported by cpufreq drivers on Linux.
    -
    FrequencyBaseMHz (Linux)
    -
    The base operating frequency of the core, as reported by some cpufreq drivers on Linux (e.g. intel_pstate).
    -
    CoreType (x86)
    -
    A string describing the kind of core, currently IntelAtom or IntelCore, as reported by the x86 CPUID instruction on some Intel processors.
    -
    LinuxCapacity (Linux)
    -
    The Linux-specific CPU capacity found in sysfs, as reported by the Linux kernel on some recent platforms. Higher values usually mean that the Linux scheduler considers the core as high-performance rather than energy-efficient.
    -
    LinuxCPUType (Linux)
    -
    The Linux-specific CPU type found in sysfs, such as intel_atom_0, as reported by future Linux kernels on some Intel processors.
    -
    DarwinCompatible (Darwin / Mac OS X)
    -
    The compatibility attribute of the CPUs as found in the IO registry on Darwin / Mac OS X. For instance apple,icestorm;ARM,v8 for energy-efficient cores and apple,firestorm;ARM,v8 on performance cores on Apple M1 CPU.
    -
    -

    See Kinds of CPU cores for details.

    -
    -
    - - - - - - -
    -
    -
    -
    Importing and exporting topologies from/to XML files
    -
    -
    -

    -

    -

    -

    hwloc offers the ability to export topologies to XML files and reload them later. This is for instance useful for loading topologies faster (see I do not want hwloc to rediscover my enormous machine topology every time I rerun a process), manipulating other nodes' topology, or avoiding the need for privileged processes (see Does hwloc require privileged access?).

    -

    Topologies may be exported to XML files thanks to hwloc_topology_export_xml(), or to a XML memory buffer with hwloc_topology_export_xmlbuffer(). The lstopo program can also serve as a XML topology export tool.

    -

    XML topologies may then be reloaded later with hwloc_topology_set_xml() and hwloc_topology_set_xmlbuffer(). The HWLOC_XMLFILE environment variable also tells hwloc to load the topology from the given XML file (see Environment Variables).

    -
    Note
    Loading XML topologies disables binding because the loaded topology may not correspond to the physical machine that loads it. This behavior may be reverted by asserting that loaded file really matches the underlying system with the HWLOC_THISSYSTEM environment variable or the HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM topology flag.
    -
    -The topology flag HWLOC_TOPOLOGY_FLAG_THISSYSTEM_ALLOWED_RESOURCES may be used to load a XML topology that contains the entire machine and restrict it to the part that is actually available to the current process (e.g. when Linux Cgroup/Cpuset are used to restrict the set of resources).
    -
    -hwloc also offers the ability to export/import Topology differences.
    -
    -XML topology files are not localized. They use a dot as a decimal separator. Therefore any exported topology can be reloaded on any other machine without requiring to change the locale.
    -
    -XML exports contain all details about the platform. It means that two very similar nodes still have different XML exports (e.g. some serial numbers or MAC addresses are different). If a less precise exporting/importing is required, one may want to look at Synthetic topologies instead.
    -

    -

    -

    -

    -libxml2 and minimalistic XML backends

    -

    hwloc offers two backends for importing/exporting XML.

    -

    First, it can use the libxml2 library for importing/exporting XML files. It features full XML support, for instance when those files have to be manipulated by non-hwloc software (e.g. a XSLT parser). The libxml2 backend is enabled by default if libxml2 development headers are available (the relevant development package is usually libxml2-devel or libxml2-dev).

    -

    If libxml2 is not available at configure time, or if --disable-libxml2 is passed, hwloc falls back to a custom backend. Contrary to the aforementioned full XML backend with libxml2, this minimalistic XML backend cannot be guaranteed to work with external programs. It should only be assumed to be compatible with the same hwloc release (even if using the libxml2 backend). Its advantage is, however, to always be available without requiring any external dependency.

    -

    If libxml2 is available but the core hwloc library should not directly depend on it, the libxml2 support may be built as a dynamicall-loaded plugin. One should pass --enable-plugins to enable plugin support (when supported) and build as plugins all component that support it. Or pass --enable-plugins=xml_libxml to only build this libxml2 support as a plugin.

    -

    -

    -

    -

    -XML import error management

    -

    Importing XML files can fail at least because of file access errors, invalid XML syntax, non-hwloc-valid XML contents, or incompatibilities between hwloc releases (see Are XML topology files compatible between hwloc releases?).

    -

    Both backend cannot detect all these errors when the input XML file or buffer is selected (when hwloc_topology_set_xml() or hwloc_topology_set_xmlbuffer() is called). Some errors such non-hwloc-valid contents can only be detected later when loading the topology with hwloc_topology_load().

    -

    It is therefore strongly recommended to check the return value of both hwloc_topology_set_xml() (or hwloc_topology_set_xmlbuffer()) and hwloc_topology_load() to handle all these errors.

    -
    -
    - - - - - - -
    -
    -
    -
    Synthetic topologies
    -
    -
    -

    -

    -

    -

    hwloc may load fake or remote topologies so as to consult them without having the underlying hardware available. Aside from loading XML topologies, hwloc also enables the building of synthetic topologies that are described by a single string listing the arity of each levels.

    -

    For instance, lstopo may create a topology made of 2 packages, containing a single NUMA node and a L2 cache above two single-threaded cores:

    -
    $ lstopo -i "pack:2 node:1 l2:1 core:2 pu:1" -
-Machine (2048MB)
-  Package L#0
-    NUMANode L#0 (P#0 1024MB)
-    L2 L#0 (4096KB)
-      Core L#0 + PU L#0 (P#0)
-      Core L#1 + PU L#1 (P#1)
-  Package L#1
-    NUMANode L#1 (P#1 1024MB)
-    L2 L#1 (4096KB)
-      Core L#2 + PU L#2 (P#2)
-      Core L#3 + PU L#3 (P#3)
-

    Replacing - with file.xml in this command line will export this topology to XML as usual.

    -
    Note
    Synthetic topologies offer a very basic way to export a topology and reimport it on another machine. It is a lot less precise than XML but may still be enough when only the hierarchy of resources matters.
    -

    -

    -

    -

    -Synthetic description string

    -

    Each item in the description string gives the type of the level and the number of such children under each object of the previous level. That is why the above topology contains 4 cores (2 cores times 2 nodes).

    -

    These type names must be written as numanode, package, core, l2u, l1i, pu, group (hwloc_obj_type_sscanf() is used for parsing the type names). They do not need to be written case-sensitively, nor entirely (as long as there is no ambiguity, 2 characters such as ma select a Machine level). Note that I/O and Misc objects are not available.

    -

    Instead of specifying the type of each level, it is possible to just specify the arities and let hwloc choose all types according to usual topologies. The following examples are therefore equivalent: 

    $ lstopo -i "2 3 4 5 6"
-$ lstopo -i "Package:2 NUMANode:3 L2Cache:4 Core:5 PU:6"
-

    NUMA nodes are handled in a special way since they are not part of the main CPU hierarchy but rather attached below it as memory children. Thus, NUMANode:3 actually means Group:3 where one NUMA node is attached below each group. These groups are merged back into the parent when possible (typically when a single NUMA node is requested below each parent).

    -

    It is also possible the explicitly attach NUMA nodes to specific levels. For instance, a topology similar to a Intel Xeon Phi processor (with 2 NUMA nodes per 16-core group) may be created with: 

    $ lstopo -i "package:1 group:4 [numa] [numa] core:16 pu:4"
-

    The root object does not appear in the synthetic description string since it is always a Machine object. Therefore the Machine type is disallowed in the description as well.

    -

    A NUMA level (with a single NUMA node) is automatically added if needed.

    -

    Each item may be followed parentheses containing a list of space-separated attributes. For instance:

      -
    • -L2iCache:2(size=32kB) specifies 2 children of 32kB level-2 instruction caches. The size may be specified in bytes (without any unit suffix) or as kB, KiB, MB, MiB, etc.
      • -
    • -NUMANode:3(memory=16MB) specifies 3 NUMA nodes with 16MB each. The size may be specified in bytes (without any unit suffix) or as GB, GiB, TB, TiB, etc.
      • -
    • -PU:2(indexes=0,2,1,3) specifies 2 PU children and the full list of OS indexes among the entire set of 4 PU objects.
      • -
    • -PU:2(indexes=numa:core) specifies 2 PU children whose OS indexes are interleaved by NUMA node first and then by package.
      • -
    • -Attributes in parentheses at the very beginning of the description apply to the root object.
      • -
    -

    hwloc command-line tools may modify a synthetic topology, for instance to customize object attributes, or to remove some objects to make the topology heterogeneous or asymmetric. See many examples in How do I create a custom heterogeneous and asymmetric topology?.

    -

    -

    -

    -

    -Loading a synthetic topology

    -

    Aside from lstopo, the hwloc programming interface offers the same ability by passing the synthetic description string to hwloc_topology_set_synthetic() before hwloc_topology_load().

    -

    Synthetic topologies are created by the synthetic component. This component may be enabled by force by setting the HWLOC_SYNTHETIC environment variable to something such as node:2 core:3 pu:4.

    -

    Loading a synthetic topology disables binding support since the topology usually does not match the underlying hardware. Binding may be reenabled as usual by setting HWLOC_THISSYSTEM=1 in the environment or by setting the HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM topology flag.

    -

    -

    -

    -

    -Exporting a topology as a synthetic string

    -

    The function hwloc_topology_export_synthetic() may export a topology as a synthetic string. It offers a convenient way to quickly describe the contents of a machine. The lstopo tool may also perform such an export by forcing the output format.

    -
    $ lstopo --of synthetic --no-io
-Package:1 L3Cache:1 L2Cache:2 L1dCache:1 L1iCache:1 Core:1 PU:2
-

    The exported string may be passed back to hwloc for recreating another similar topology (see also Are synthetic strings compatible between hwloc releases?). The entire tree will be similar, but some attributes such as the processor model will be missing.

    -

    Such an export is only possible if the topology is totally symmetric. It means that the symmetric_subtree field of the root object is set. Also memory children should be attached in a symmetric way (e.g. the same number of memory children below each Package object, etc.). However, I/O devices and Misc objects are ignored when looking at symmetry and exporting the string.

    -
    -
    - - - - - - -
    -
    -
    -
    Interoperability With Other Software
    -
    -
    -

    -

    -

    -

    Although hwloc offers its own portable interface, it still may have to interoperate with specific or non-portable libraries that manipulate similar kinds of objects. hwloc therefore offers several specific "helpers" to assist converting between those specific interfaces and hwloc.

    -

    Some external libraries may be specific to a particular OS; others may not always be available. The hwloc core therefore generally does not explicitly depend on these types of libraries. However, when a custom application uses or otherwise depends on such a library, it may optionally include the corresponding hwloc helper to extend the hwloc interface with dedicated helpers.

    -

    Most of these helpers use structures that are specific to these external libraries and only meaningful on the local machine. If so, the helper requires the input topology to match the current machine. Some helpers also require I/O device discovery to be supported and enabled for the current topology.

    -
    -
    Linux specific features
    -

    hwloc/linux.h offers Linux-specific helpers that utilize some non-portable features of the Linux system, such as binding threads through their thread ID ("tid") or parsing kernel CPU mask files. See Linux-specific helpers.

    -

    -
    -
    Windows specific features
    -

    hwloc/windows.h offers Windows-specific helpers to query information about Windows processor groups. See Windows-specific helpers.

    -

    -
    -
    Linux libnuma
    -

    hwloc/linux-libnuma.h provides conversion helpers between hwloc CPU sets and libnuma-specific types, such as bitmasks. It helps you use libnuma memory-binding functions with hwloc CPU sets. See Interoperability with Linux libnuma bitmask and Interoperability with Linux libnuma unsigned long masks.

    -

    -
    -
    Glibc
    -

    hwloc/glibc-sched.h offers conversion routines between Glibc and hwloc CPU sets in order to use hwloc with functions such as sched_getaffinity() or pthread_attr_setaffinity_np(). See Interoperability with glibc sched affinity.

    -

    -
    -
    OpenFabrics Verbs
    -

    hwloc/openfabrics-verbs.h helps interoperability with the OpenFabrics Verbs interface. For example, it can return a list of processors near an OpenFabrics device. It may also return the corresponding OS device hwloc object for further information (if I/O device discovery is enabled). See Interoperability with OpenFabrics.

    -

    -
    -
    OpenCL
    -

    hwloc/opencl.h enables interoperability with the OpenCL interface. Only the AMD and NVIDIA implementations currently offer locality information. It may return the list of processors near a GPU given as a cl_device_id. It may also return the corresponding OS device hwloc object for further information (if I/O device discovery is enabled). See Interoperability with OpenCL.

    -

    -
    -
    oneAPI Level Zero
    -

    hwloc/levelzero.h enables interoperability with the oneAPI Level Zero interface. It may return the list of processors near an accelerator or GPU. It may also return the corresponding OS device hwloc object for further information (if I/O device discovery is enabled). See Interoperability with the oneAPI Level Zero interface..

    -

    -
    -
    AMD ROCm SMI Library (RSMI)
    -

    hwloc/rsmi.h enables interoperability with the AMD ROCm SMI interface. It may return the list of processors near an AMD GPU. It may also return the corresponding OS device hwloc object for further information (if I/O device discovery is enabled). See Interoperability with the ROCm SMI Management Library.

    -

    -
    -
    NVIDIA CUDA
    -

    hwloc/cuda.h and hwloc/cudart.h enable interoperability with NVIDIA CUDA Driver and Runtime interfaces. For instance, it may return the list of processors near NVIDIA GPUs. It may also return the corresponding OS device hwloc object for further information (if I/O device discovery is enabled). See Interoperability with the CUDA Driver API and Interoperability with the CUDA Runtime API.

    -

    -
    -
    NVIDIA Management Library (NVML)
    -

    hwloc/nvml.h enables interoperability with the NVIDIA NVML interface. It may return the list of processors near a NVIDIA GPU given as a nvmlDevice_t. It may also return the corresponding OS device hwloc object for further information (if I/O device discovery is enabled). See Interoperability with the NVIDIA Management Library.

    -

    -
    -
    NVIDIA displays
    -

    hwloc/gl.h enables interoperability with NVIDIA displays using the NV-CONTROL X extension (NVCtrl library). If I/O device discovery is enabled, it may return the OS device hwloc object that corresponds to a display given as a name such as :0.0 or given as a port/device pair (server/screen). See Interoperability with OpenGL displays.

    -

    -
    -
    Taskset command-line tool
    -

    The taskset command-line tool is widely used for binding processes. It manipulates CPU set strings in a format that is slightly different from hwloc's one (it does not divide the string in fixed-size subsets and separates them with commas). To ease interoperability, hwloc offers routines to convert hwloc CPU sets from/to taskset-specific string format. See for instance hwloc_bitmap_taskset_snprintf() in The bitmap API.

    -

    Most hwloc command-line tools also support the --taskset option to manipulate taskset-specific strings.

    -

    -
    -
    -
    -
    - - - - - - -
    -
    -
    -
    Thread Safety
    -
    -
    -

    -

    -

    -

    Like most libraries that mainly fill data structures, hwloc is not thread safe but rather reentrant: all state is held in a hwloc_topology_t instance without mutex protection. That means, for example, that two threads can safely operate on and modify two different hwloc_topology_t instances, but they should not simultaneously invoke functions that modify the same instance. Similarly, one thread should not modify a hwloc_topology_t instance while another thread is reading or traversing it. However, two threads can safely read or traverse the same hwloc_topology_t instance concurrently.

    -

    When running in multiprocessor environments, be aware that proper thread synchronization and/or memory coherency protection is needed to pass hwloc data (such as hwloc_topology_t pointers) from one processor to another (e.g., a mutex, semaphore, or a memory barrier). Note that this is not a hwloc-specific requirement, but it is worth mentioning.

    -

    For reference, hwloc_topology_t modification operations include (but may not be limited to):

    -
    -
    Creation and destruction
    -

    hwloc_topology_init(), hwloc_topology_load(), hwloc_topology_destroy() (see Topology Creation and Destruction) imply major modifications of the structure, including freeing some objects. No other thread cannot access the topology or any of its objects at the same time.

    -

    Also references to objects inside the topology are not valid anymore after these functions return.

    -

    -
    -
    Runtime topology modifications
    -

    hwloc_topology_insert_misc_object(), hwloc_topology_alloc_group_object(), and hwloc_topology_insert_group_object() (see Modifying a loaded Topology) may modify the topology significantly by adding objects inside the tree, changing the topology depth, etc.

    -

    hwloc_distances_add_commit() and hwloc_distances_remove() (see Add distances between objects) modify the list of distance structures in the topology, and the former may even insert new Group objects.

    -

    hwloc_memattr_register() and hwloc_memattr_set_value() (see Managing memory attributes) modify the memory attributes of the topology.

    -

    hwloc_topology_restrict() modifies the topology even more dramatically by removing some objects.

    -

    hwloc_topology_refresh() updates some internal cached structures. (see below).

    -

    Although references to former objects may still be valid after insertion or restriction, it is strongly advised to not rely on any such guarantee and always re-consult the topology to reacquire new instances of objects.

    -

    -
    -
    Consulting distances
    -

    hwloc_distances_get() and its variants are thread-safe except if the topology was recently modified (because distances may involve objects that were removed).

    -

    Whenever the topology is modified (see above), hwloc_topology_refresh() should be called in the same thread-safe context to force the refresh of internal distances structures. A call to hwloc_distances_get() may also refresh distances-related structures.

    -

    Once this refresh has been performed, multiple hwloc_distances_get() may then be performed concurrently by multiple threads.

    -

    -
    -
    Consulting memory attributes
    -

    Functions consulting memory attributes in hwloc/memattrs.h are thread-safe except if the topology was recently modified (because memory attributes may involve objects that were removed).

    -

    Whenever the topology is modified (see above), hwloc_topology_refresh() should be called in the same thread-safe context to force the refresh of internal memory attribute structures. A call to hwloc_memattr_get_value() or hwloc_memattr_get_targets() may also refresh internal structures for a given memory attribute.

    -

    Once this refresh has been performed, multiple functions consulting memory attributes may then be performed concurrently by multiple threads.

    -

    -
    -
    Locating topologies
    -

    hwloc_topology_set_* (see Topology Detection Configuration and Query) do not modify the topology directly, but they do modify internal structures describing the behavior of the upcoming invocation of hwloc_topology_load(). Hence, all of these functions should not be used concurrently.

    -

    -
    -
    -
    -
    - - - - - - -
    -
    -
    -
    Components and plugins
    -
    -
    -

    -

    -

    -

    hwloc is organized in components that are responsible for discovering objects. Depending on the topology configuration, some components will be used, some will be ignored. The usual default is to enable the native operating system component, (e.g. linux or solaris) and the pci miscellaneous component. If available, an architecture-specific component (such as x86) may also improve the topology detection.

    -

    If a XML topology is loaded, the xml discovery component will be used instead of all other components. It internally uses a specific class of components for the actual XML import/export routines (xml_libxml and xml_nolibxml) but these will not be discussed here (see libxml2 and minimalistic XML backends).

    -

    -

    -

    -

    -Components enabled by default

    -

    The hwloc core contains a list of components sorted by priority. Each one is enabled as long as it does not conflict with the previously enabled ones. This includes native operating system components, architecture-specific ones, and if available, I/O components such as pci.

    -

    Usually the native operating system component (when it exists, e.g. linux or aix) is enabled first. Then hwloc looks for an architecture specific component (e.g. x86). Finally there also exist a basic component (no_os) that just tries to discover the number of PUs in the system.

    -

    Each component discovers as much topology information as possible. Most of them, including most native OS components, do nothing unless the topology is still empty. Some others, such as x86 and pci, can complete and annotate what other backends found earlier. Discovery is performed by phases: CPUs are first discovered, then memory is attached, then PCI, etc.

    -

    Default priorities ensure that clever components are invoked first. Native operating system components have higher priorities, and are therefore invoked first, because they likely offer very detailed topology information. If needed, it will be later extended by architecture-specific information (e.g. from the x86 component).

    -

    If any configuration function such as hwloc_topology_set_xml() is used before loading the topology, the corresponding component is enabled first. Then, as usual, hwloc enables any other component (based on priorities) that does not conflict.

    -

    Certain components that manage a virtual topology, for instance XML topology import or synthetic topology description, conflict with all other components. Therefore, one of them may only be loaded (e.g. with hwloc_topology_set_xml()) if no other component is enabled.

    -

    The environment variable HWLOC_COMPONENTS_VERBOSE may be set to get verbose messages about component registration (including their priority) and enabling.

    -

    -

    -

    -

    -Selecting which components to use

    -

    If no topology configuration functions such as hwloc_topology_set_synthetic() have been called, plugins may be selected with environment variables such as HWLOC_XMLFILE, HWLOC_SYNTHETIC, HWLOC_FSROOT, or HWLOC_CPUID_PATH (see Environment Variables).

    -

    Finally, the environment variable HWLOC_COMPONENTS resets the list of selected components. If the variable is set and empty (or set to a single comma separating nothing, since some operating systems do not accept empty variables), the normal plugin priority order is used.

    -

    If the variable is set to x86 in this variable will cause the x86 component to take precedence over any other component, including the native operating system component. It is therefore loaded first, before hwloc tries to load all remaining non-conflicting components. In this case, x86 would take care of discovering everything it supports, instead of only completing what the native OS information. This may be useful if the native component is buggy on some platforms.

    -

    It is possible to prevent some components from being loaded by prefixing their name with - in the list. For instance x86,-pci will load the x86 component, then let hwloc load all the usual components except pci. A single component phase may also be blacklisted, for instance with -linux:io. hwloc_topology_set_components() may also be used inside the program to prevent the loading of a specific component (or phases) for the target topology.

    -

    It is possible to prevent all remaining components from being loaded by placing stop in the environment variable. Only the components listed before this keyword will be enabled.

    -

    -

    -

    -

    -Loading components from plugins

    -

    Components may optionally be built as plugins so that the hwloc core library does not directly depend on their dependencies (for instance the libpciaccess library). Plugin support may be enabled with the --enable-plugins configure option. All components buildable as plugins will then be built as plugins. The configure option may be given a comma-separated list of component names to specify the exact list of components to build as plugins.

    -

    Plugins are built as independent dynamic libraries that are installed in $libdir/hwloc. All plugins found in this directory are loaded during topology_init() (unless blacklisted in HWLOC_PLUGINS_BLACKLIST, see Environment Variables). A specific list of directories (colon-separated) to scan may be specified in the HWLOC_PLUGINS_PATH environment variable.

    -

    Note that loading a plugin just means that the corresponding component is registered to the hwloc core. Components are then only enabled if the topology configuration requests it, as explained in the previous sections.

    -

    Also note that plugins should carefully be enabled and used when embedding hwloc in another project, see Embedding hwloc in Other Software for details.

    -

    -

    -

    -

    -Existing components and plugins

    -

    All components distributed within hwloc are listed below. The list of actually available components may be listed at running with the HWLOC_COMPONENTS_VERBOSE environment variable (see Environment Variables).

    -
    -
    linux
    -
    The official component for discovering CPU, memory and I/O devices on Linux. It discovers PCI devices without the help of external libraries such as libpciaccess, but requires the pci component for adding vendor/device names to PCI objects. It also discovers many kinds of Linux-specific OS devices.
    -
    aix, darwin, freebsd, hpux, netbsd, solaris, windows
    -
    Each officially supported operating system has its own native component, which is statically built when supported, and which is used by default.
    -
    x86
    -
    The x86 architecture (either 32 or 64 bits) has its own component that may complete or replace the previously-found CPU information. It is statically built when supported.
    -
    bgq
    -
    This component is specific to IBM BlueGene/Q compute node (running CNK). It is built and enabled by default when --host=powerpc64-bgq-linux is passed to configure (see How do I build hwloc for BlueGene/Q?).
    -
    no_os
    -
    A basic component that just tries to detect the number of processing units in the system. It mostly serves on operating systems that are not natively supported. It is always statically built.
    -
    pci
    -
    PCI object discovery uses the external pciaccess library (aka libpciaccess); see I/O Devices. It may also annotate existing PCI devices with vendor and device names. It may be built as a plugin.
    -
    opencl
    -
    The OpenCL component creates co-processor OS device objects such as opencl0d0 (first device of the first OpenCL platform) or opencl1d3 (fourth device of the second platform). Only the AMD and NVIDIA OpenCL implementations currently offer locality information. It may be built as a plugin.
    -
    rsmi
    -
    This component creates GPU OS device objects such as rsmi0 for describing AMD GPUs. It may be built as a plugin.
    -
    levelzero
    -
    This component creates co-processor OS device objects such as ze0 for describing oneAPI Level Zero devices. It may also create sub-OS-devices such as ze0.0 inside those devices. It may be built as a plugin.
    -
    cuda
    -
    This component creates co-processor OS device objects such as cuda0 that correspond to NVIDIA GPUs used with CUDA library. It may be built as a plugin.
    -
    nvml
    -
    Probing the NVIDIA Management Library creates OS device objects such as nvml0 that are useful for batch schedulers. It also detects the actual PCIe link bandwidth without depending on power management state and without requiring administrator privileges. It may be built as a plugin.
    -
    gl
    -
    Probing the NV-CONTROL X extension (NVCtrl library) creates OS device objects such as :0.0 corresponding to NVIDIA displays. They are useful for graphical applications that need to place computation and/or data near a rendering GPU. It may be built as a plugin.
    -
    synthetic
    -
    Synthetic topology support (see Synthetic topologies) is always built statically.
    -
    xml
    -
    XML topology import (see Importing and exporting topologies from/to XML files) is always built statically. It internally uses one of the XML backends (see libxml2 and minimalistic XML backends).
      -
    • -xml_nolibxml is a basic and hwloc-specific XML import/export. It is always statically built.
      • -
    • -xml_libxml relies on the external libxml2 library for provinding a feature-complete XML import/export. It may be built as a plugin.
      • -
    -
    -
    fake
    -
    A dummy plugin that does nothing but is used for debugging plugin support.
    -
    -
    -
    - - - - - - -
    -
    -
    -
    Embedding hwloc in Other Software
    -
    -
    -

    -

    -

    -

    It can be desirable to include hwloc in a larger software package (be sure to check out the LICENSE file) so that users don't have to separately download and install it before installing your software. This can be advantageous to ensure that your software uses a known-tested/good version of hwloc, or for use on systems that do not have hwloc pre-installed.

    -

    When used in "embedded" mode, hwloc will:

    -
      -
    • not install any header files
      • -
    • not build any documentation files
      • -
    • not build or install any executables or tests
      • -
    • not build libhwloc.* – instead, it will build libhwloc_embedded.*
      • -
    -

    There are two ways to put hwloc into "embedded" mode. The first is directly from the configure command line:

    -
    shell$ ./configure --enable-embedded-mode ...
-

    The second requires that your software project uses the GNU Autoconf / Automake / Libtool tool chain to build your software. If you do this, you can directly integrate hwloc's m4 configure macro into your configure script. You can then invoke hwloc's configuration tests and build setup by calling a m4 macro (see below).

    -

    Although hwloc dynamic shared object plugins may be used in embedded mode, the embedder project will have to manually setup dlopen or libltdl in its build system so that hwloc can load its plugins at run time. Also, embedders should be aware of complications that can arise due to public and private linker namespaces (e.g., if the embedder project is loaded into a private namespace and then hwloc tries to dynamically load its plugins, such loading may fail since the hwloc plugins can't find the hwloc symbols they need). The embedder project is strongly advised not to use hwloc's dynamically loading plugins / dlopen / libltdl capability.

    -

    -

    -

    -

    -Using hwloc's M4 Embedding Capabilities

    -

    Every project is different, and there are many different ways of integrating hwloc into yours. What follows is one example of how to do it.

    -

    If your project uses recent versions Autoconf, Automake, and Libtool to build, you can use hwloc's embedded m4 capabilities. We have tested the embedded m4 with projects that use Autoconf 2.65, Automake 1.11.1, and Libtool 2.2.6b. Slightly earlier versions of may also work but are untested. Autoconf versions prior to 2.65 are almost certain to not work.

    -

    You can either copy all the config/hwloc*m4 files from the hwloc source tree to the directory where your project's m4 files reside, or you can tell aclocal to find more m4 files in the embedded hwloc's "config" subdirectory (e.g., add "-Ipath/to/embedded/hwloc/config" to your Makefile.am's ACLOCAL_AMFLAGS).

    -

    The following macros can then be used from your configure script (only HWLOC_SETUP_CORE must be invoked if using the m4 macros):

    -
      -

    • HWLOC_SETUP_CORE(config-dir-prefix, action-upon-success, action-upon-failure, print_banner_or_not): Invoke the hwloc configuration tests and setup the hwloc tree to build. The first argument is the prefix to use for AC_OUTPUT files – it's where the hwloc tree is located relative to $top_srcdir. Hence, if your embedded hwloc is located in the source tree at contrib/hwloc, you should pass [contrib/hwloc] as the first argument. If HWLOC_SETUP_CORE and the rest of configure completes successfully, then "make" traversals of the hwloc tree with standard Automake targets (all, clean, install, etc.) should behave as expected. For example, it is safe to list the hwloc directory in the SUBDIRS of a higher-level Makefile.am. The last argument, if not empty, will cause the macro to display an announcement banner that it is starting the hwloc core configuration tests.

      -

      HWLOC_SETUP_CORE will set the following environment variables and AC_SUBST them: HWLOC_EMBEDDED_CFLAGS, HWLOC_EMBEDDED_CPPFLAGS, and HWLOC_EMBEDDED_LIBS. These flags are filled with the values discovered in the hwloc-specific m4 tests, and can be used in your build process as relevant. The _CFLAGS, _CPPFLAGS, and _LIBS variables are necessary to build libhwloc (or libhwloc_embedded) itself.

      -

      HWLOC_SETUP_CORE also sets HWLOC_EMBEDDED_LDADD environment variable (and AC_SUBSTs it) to contain the location of the libhwloc_embedded.la convenience Libtool archive. It can be used in your build process to link an application or other library against the embedded hwloc library.

      -

      NOTE: If the HWLOC_SET_SYMBOL_PREFIX macro is used, it must be invoked before HWLOC_SETUP_CORE.

      -
      • -
    • HWLOC_BUILD_STANDALONE: HWLOC_SETUP_CORE defaults to building hwloc in an "embedded" mode (described above). If HWLOC_BUILD_STANDALONE is invoked *before* HWLOC_SETUP_CORE, the embedded definitions will not apply (e.g., libhwloc.la will be built, not libhwloc_embedded.la).
      • -
    • HWLOC_SET_SYMBOL_PREFIX(foo_): Tells the hwloc to prefix all of hwloc's types and public symbols with "foo_"; meaning that function hwloc_init() becomes foo_hwloc_init(). Enum values are prefixed with an upper-case translation if the prefix supplied; HWLOC_OBJ_CORE becomes FOO_hwloc_OBJ_CORE. This is recommended behavior if you are including hwloc in middleware – it is possible that your software will be combined with other software that links to another copy of hwloc. If both uses of hwloc utilize different symbol prefixes, there will be no type/symbol clashes, and everything will compile, link, and run successfully. If you both embed hwloc without changing the symbol prefix and also link against an external hwloc, you may get multiple symbol definitions when linking your final library or application.
      • -
    • HWLOC_SETUP_DOCS, HWLOC_SETUP_UTILS, HWLOC_SETUP_TESTS: These three macros only apply when hwloc is built in "standalone" mode (i.e., they should NOT be invoked unless HWLOC_BUILD_STANDALONE has already been invoked).
      • -
    • HWLOC_DO_AM_CONDITIONALS: If you embed hwloc in a larger project and build it conditionally with Automake (e.g., if HWLOC_SETUP_CORE is invoked conditionally), you must unconditionally invoke HWLOC_DO_AM_CONDITIONALS to avoid warnings from Automake (for the cases where hwloc is not selected to be built). This macro is necessary because hwloc uses some AM_CONDITIONALs to build itself, and AM_CONDITIONALs cannot be defined conditionally. Note that it is safe (but unnecessary) to call HWLOC_DO_AM_CONDITIONALS even if HWLOC_SETUP_CORE is invoked unconditionally. If you are not using Automake to build hwloc, this macro is unnecessary (and will actually cause errors because it invoked AM_* macros that will be undefined).
      • -
    -

    NOTE: When using the HWLOC_SETUP_CORE m4 macro, it may be necessary to explicitly invoke AC_CANONICAL_TARGET (which requires config.sub and config.guess) and/or AC_USE_SYSTEM_EXTENSIONS macros early in the configure script (e.g., after AC_INIT but before AM_INIT_AUTOMAKE). See the Autoconf documentation for further information.

    -

    Also note that hwloc's top-level configure.ac script uses exactly the macros described above to build hwloc in a standalone mode (by default). You may want to examine it for one example of how these macros are used.

    -

    -

    -

    -

    -Example Embedding hwloc

    -

    Here's an example of integrating with a larger project named sandbox that already uses Autoconf, Automake, and Libtool to build itself:

    -
    # First, cd into the sandbox project source tree
-shell$ cd sandbox
-shell$ cp -r /somewhere/else/hwloc-<version> my-embedded-hwloc
-shell$ edit Makefile.am
-  1. Add "-Imy-embedded-hwloc/config" to ACLOCAL_AMFLAGS
-  2. Add "my-embedded-hwloc" to SUBDIRS
-  3. Add "$(HWLOC_EMBEDDED_LDADD)" and "$(HWLOC_EMBEDDED_LIBS)" to 
-     sandbox's executable's LDADD line.  The former is the name of the 
-     Libtool convenience library that hwloc will generate.  The latter 
-     is any dependent support libraries that may be needed by 
-     $(HWLOC_EMBEDDED_LDADD).
-  4. Add "$(HWLOC_EMBEDDED_CFLAGS)" to AM_CFLAGS
-  5. Add "$(HWLOC_EMBEDDED_CPPFLAGS)" to AM_CPPFLAGS
-shell$ edit configure.ac
-  1. Add "HWLOC_SET_SYMBOL_PREFIX(sandbox_hwloc_)" line
-  2. Add "HWLOC_SETUP_CORE([my-embedded-hwloc], [happy=yes], [happy=no])" line
-  3. Add error checking for happy=no case
-shell$ edit sandbox.c
-  1. Add #include <hwloc.h>
-  2. Add calls to sandbox_hwloc_init() and other hwloc API functions
-

    Now you can bootstrap, configure, build, and run the sandbox as normal – all calls to "sandbox_hwloc_*" will use the embedded hwloc rather than any system-provided copy of hwloc.

    -
    -
    - - - - - - -
    -
    -
    -
    Frequently Asked Questions (FAQ)
    -
    -
    -

    -

    -

    -

    -Concepts

    -

    -I only need binding, why should I use hwloc ?

    -

    hwloc is its portable API that works on a variety of operating systems. It supports binding of threads, processes and memory buffers (see CPU binding and Memory binding). Even if some features are not supported on some systems, using hwloc is much easier than reimplementing your own portability layer.

    -

    Moreover, hwloc provides knowledge of cores and hardware threads. It offers easy ways to bind tasks to individual hardware threads, or to entire multithreaded cores, etc. See How may I ignore symmetric multithreading, hyper-threading, etc. in hwloc?. Most alternative software for binding do not even know whether each core is single-threaded, multithreaded or hyper-threaded. They would bind to individual threads without any way to know whether multiple tasks are in the same physical core.

    -

    However, using hwloc comes with an overhead since a topology must be loaded before gathering information and binding tasks or memory. Fortunately this overhead may be significantly reduced by filtering non-interesting information out of the topology.

    -


    - For instance, the default configuration is to keep all objects enabled (except I/Os and instruction caches). The following code tells hwloc to build a much smaller topology that only contains Cores (explicitly filtered-in below), hardware threads (PUs, cannot be filtered-out), NUMA nodes (cannot be filtered-out), and the root object (usually a Machine; the root cannot be removed without breaking the tree):

    -
    hwloc_topology_t topology;
-hwloc_topology_init(&topology);
-/* filter everything out */
-hwloc_topology_set_all_types_filter(topology, HWLOC_TYPE_FILTER_KEEP_NONE);
-/* filter Cores back in */
-hwloc_topology_set_type_filter(topology, HWLOC_OBJ_CORE, HWLOC_TYPE_FILTER_KEEP_ALL);
-hwloc_topology_load(topology);
-

    However, one should remember that filtering such objects out removes locality information from the hwloc tree. For instance, we do not know anymore which PU is close to which NUMA node. This would be useful to applications that explicitly want to place specific memory buffers close to specific tasks. Those applications should also tell hwloc to keep Group objects that bring structure information: 

    hwloc_topology_set_type_filter(topology, HWLOC_OBJ_GROUP, HWLOC_TYPE_FILTER_KEEP_STRUCTURE);
-


    - Starting with hwloc 2.8, it is also possible to ignore distances between objects, memory performance attributes, and kinds of CPU cores, by setting topology flags before load: 

    [...]
-/* disable distances, memory attributes and CPU kinds */
-hwloc_topology_set_flags(topology, HWLOC_TOPOLOGY_FLAG_NO_DISTANCES
-                                   |HWLOC_TOPOLOGY_FLAG_NO_MEMATTRS
-                                   |HWLOC_TOPOLOGY_FLAG_NO_CPUKINDS);
-[...]
-hwloc_topology_load(topology);
-

    -Should I use logical or physical/OS indexes? and how?

    -

    One of the original reasons why hwloc was created is that physical/OS indexes (obj->os_index) are often crazy and unpredictable: processors numbers are usually non-contiguous (processors 0 and 1 are not physically close), they vary from one machine to another, and may even change after a BIOS or system update. This numbers make task placement hardly portable. Moreover some objects have no physical/OS numbers (caches), and some objects have non-unique numbers (core numbers are only unique within a socket). Physical/OS indexes are only guaranteed to exist and be unique for PU and NUMA nodes.

    -

    hwloc therefore introduces logical indexes (obj->logical_index) which are portable, contiguous and logically ordered (based on the resource organization in the locality tree). In general, one should only use logical indexes and just let hwloc do the internal conversion when really needed (when talking to the OS and hardware).

    -

    hwloc developers recommends that users do not use physical/OS indexes unless they really know what they are doing. The main reason for still using physical/OS indexes is when interacting with non-hwloc tools such as numactl or taskset, or when reading hardware information from raw sources such as /proc/cpuinfo.

    -

    lstopo options -l and -p may be used to switch between logical indexes (prefixed with L#) and physical/OS indexes (P#). Converting one into the other may also be achieved with hwloc-calc which may manipulate either logical or physical indexes as input or output. See also hwloc-calc.

    -
    # Convert PU with physical number 3 into logical number
-$ hwloc-calc -I pu --physical-input --logical-output pu:3
-5
-
-# Convert a set of NUMA nodes from logical to physical
-# (beware that the output order may not match the input order)
-$ hwloc-calc -I numa --logical-input --physical-output numa:2-3 numa:7
-0,2,5
-

    -hwloc is only a structural model, it ignores performance models, memory bandwidth, etc.?

    -

    hwloc is indeed designed to provide applications with a structural model of the platform. This is an orthogonal approach to describing the machine with performance models, for instance using memory bandwidth or latencies measured by benchmarks. We believe that both approaches are important for helping application make the most of the hardware.

    -

    For instance, on a dual-processor host with four cores each, hwloc clearly shows which four cores are together. Latencies between all pairs of cores of the same processor are likely identical, and also likely lower than the latency between cores of different processors. However, the structural model cannot guarantee such implementation details. On the other side, performance models would reveal such details without always clearly identifying which cores are in the same processor.

    -

    The focus of hwloc is mainly of the structural modeling side. However, hwloc lets user adds performance information to the topology through distances (see Distances), memory attributes (see Memory Attributes) or even custom annotations (see How do I annotate the topology with private notes?). hwloc may also use such distance information for grouping objects together (see hwloc only has a one-dimensional view of the architecture, it ignores distances? and What are these Group objects in my topology?).

    -

    -hwloc only has a one-dimensional view of the architecture, it ignores distances?

    -

    hwloc places all objects in a tree. Each level is a one-dimensional view of a set of similar objects. All children of the same object (siblings) are assumed to be equally interconnected (same distance between any of them), while the distance between children of different objects (cousins) is supposed to be larger.

    -

    Modern machines exhibit complex hardware interconnects, so this tree may miss some information about the actual physical distances between objects. The hwloc topology may therefore be annotated with distance information that may be used to build a more realistic representation (multi-dimensional) of each level. For instance, there can be a distance matrix that representing the latencies between any pair of NUMA nodes if the BIOS and/or operating system reports them.

    -

    For more information about the hwloc distances, see Distances.

    -

    -What are these Group objects in my topology?

    -

    hwloc comes with a set of predefined object types (Core, Package, NUMA node, Caches) that match the vast majority of hardware platforms. The HWLOC_OBJ_GROUP type was designed for cases where this set is not sufficient. Groups may be used anywhere to add more structure information to the topology, for instance to show that 2 out of 4 NUMA nodes are actually closer than the others. When applicable, the subtype field describes why a Group was actually added (see also Normal attributes).

    -

    hwloc currently uses Groups for the following reasons:

      -
    • -NUMA parents when memory locality does not match any existing object.
      • -
    • -I/O parents when I/O locality does not match any existing object.
      • -
    • -Distance-based groups made of close objects.
      • -
    • -AMD Bulldozer dual-core compute units (subtype is ComputeUnit, in the x86 backend), but these objects are usually merged with the L2 caches.
      • -
    • -Intel Extended Topology Enumeration levels (in the x86 backend).
      • -
    • -Windows processor groups when HWLOC_WINDOWS_PROCESSOR_GROUP_OBJS=1 is set in the environment (except if they contain exactly a single NUMA node, or a single Package, etc.).
      • -
    • -IBM S/390 "Books" on Linux (subtype is Book).
      • -
    • -Linux Clusters of CPUs (subtype is Cluster), for instance for ARM cores sharing of some internal cache or bus, or x86 cores sharing a L2 cache (since Linux kernel 5.16). HWLOC_DONT_MERGE_CLUSTER_GROUPS=1 may be set in the environment to disable the automerging of these groups with identical caches, etc.
      • -
    • -AIX unknown hierarchy levels.
      • -
    -

    hwloc Groups are only kept if no other object has the same locality information. It means that a Group containing a single child is merged into that child. And a Group is merged into its parent if it is its only child. For instance a Windows processor group containing a single NUMA node would be merged with that NUMA node since it already contains the relevant hierarchy information.

    -

    When inserting a custom Group with hwloc_hwloc_topology_insert_group_object(), this merging may be disabled by setting its dont_merge attribute.

    -

    -What happens if my topology is asymmetric?

    -

    hwloc supports asymmetric topologies even if most platforms are usually symmetric. For example, there could be different types of processors in a single machine, each with different numbers of cores, symmetric multithreading, or levels of caches.

    -

    In practice, asymmetric topologies are rare but occur for at least two reasons:

      -
    • -Intermediate groups may added for I/O affinity: on a 4-package machine, an I/O bus may be connected to 2 packages. These packages are below an additional Group object, while the other packages are not (see also What are these Group objects in my topology?).
      • -
    • -If only part of a node is available to the current process, for instance because the resource manager uses Linux Cgroups to restrict process resources, some cores (or NUMA nodes) will disappear from the topology (unless flag HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED was passed). On a 32-core machine where 12 cores were allocated to the process, this may lead to one CPU package with 8 cores, another one with only 4 cores, and two missing packages.
      • -
    -

    To understand how hwloc manages such cases, one should first remember the meaning of levels and cousin objects. All objects of the same type are gathered as horizontal levels with a given depth. They are also connected through the cousin pointers of the hwloc_obj structure. Object attribute (cache depth and type, group depth) are also taken in account when gathering objects as horizontal levels. To be clear: there will be one level for L1i caches, another level for L1d caches, another one for L2, etc.

    -

    If the topology is asymmetric (e.g., if a group is missing above some processors), a given horizontal level will still exist if there exist any objects of that type. However, some branches of the overall tree may not have an object located in that horizontal level. Note that this specific hole within one horizontal level does not imply anything for other levels. All objects of the same type are gathered in horizontal levels even if their parents or children have different depths and types.

    -

    See the diagram in Terms and Definitions for a graphical representation of such topologies.

    -

    Moreover, it is important to understand that a same parent object may have children of different types (and therefore, different depths). These children are therefore siblings (because they have the same parent), but they are not cousins (because they do not belong to the same horizontal level).

    -

    -What happens to my topology if I disable symmetric multithreading, hyper-threading, etc. in the system?

    -

    hwloc creates one PU (processing unit) object per hardware thread. If your machine supports symmetric multithreading, for instance Hyper-Threading, each Core object may contain multiple PU objects: 

    $ lstopo -
-...
-  Core L#0
-    PU L#0 (P#0)
-    PU L#1 (P#2)
-  Core L#1
-    PU L#2 (P#1)
-    PU L#3 (P#3)
-

    x86 machines usually offer the ability to disable hyper-threading in the BIOS. Or it can be disabled on the Linux kernel command-line at boot time, or later by writing in sysfs virtual files.

    -

    If you do so, the hwloc topology structure does not significantly change, but some PU objects will not appear anymore. No level will disappear, you will see the same number of Core objects, but each of them will contain a single PU now. The PU level does not disappear either (remember that hwloc topologies always contain a PU level at the bottom of the topology) even if there is a single PU object per Core parent. 

    $ lstopo -
-...
-  Core L#0
-    PU L#0 (P#0)
-  Core L#1
-    PU L#1 (P#1)
-

    -How may I ignore symmetric multithreading, hyper-threading, etc. in hwloc?

    -

    First, see What happens to my topology if I disable symmetric multithreading, hyper-threading, etc. in the system? for more information about multithreading.

    -

    If you need to ignore symmetric multithreading in software, you should likely manipulate hwloc Core objects directly: 

    /* get the number of cores */
-unsigned nbcores = hwloc_get_nbobjs_by_type(topology, HWLOC_OBJ_CORE);
-...
-/* get the third core below the first package */
-hwloc_obj_t package, core;
-package = hwloc_get_obj_by_type(topology, HWLOC_OBJ_PACKAGE, 0);
-core = hwloc_get_obj_inside_cpuset_by_type(topology, package->cpuset,
-                                           HWLOC_OBJ_CORE, 2);
-

    Whenever you want to bind a process or thread to a core, make sure you singlify its cpuset first, so that the task is actually bound to a single thread within this core (to avoid useless migrations). 

    /* bind on the second core */
-hwloc_obj_t core = hwloc_get_obj_by_type(topology, HWLOC_OBJ_CORE, 1);
-hwloc_cpuset_t set = hwloc_bitmap_dup(core->cpuset);
-hwloc_bitmap_singlify(set);
-hwloc_set_cpubind(topology, set, 0);
-hwloc_bitmap_free(set);
-

    With hwloc-calc or hwloc-bind command-line tools, you may specify that you only want a single-thread within each core by asking for their first PU object: 

    $ hwloc-calc core:4-7
-0x0000ff00
-$ hwloc-calc core:4-7.pu:0
-0x00005500
-

    When binding a process on the command-line, you may either specify the exact thread that you want to use, or ask hwloc-bind to singlify the cpuset before binding 

    $ hwloc-bind core:3.pu:0 -- echo "hello from first thread on core #3"
-hello from first thread on core #3
-...
-$ hwloc-bind core:3 --single -- echo "hello from a single thread on core #3"
-hello from a single thread on core #3
-

    -

    -

    -

    -Advanced

    -

    -I do not want hwloc to rediscover my enormous machine topology every time I rerun a process

    -

    Although the topology discovery is not expensive on common machines, its overhead may become significant when multiple processes repeat the discovery on large machines (for instance when starting one process per core in a parallel application). The machine topology usually does not vary much, except if some cores are stopped/restarted or if the administrator restrictions are modified. Thus rediscovering the whole topology again and again may look useless.

    -

    For this purpose, hwloc offers XML import/export and shared memory features.

    -

    XML lets you save the discovered topology to a file (for instance with the lstopo program) and reload it later by setting the HWLOC_XMLFILE environment variable. The HWLOC_THISSYSTEM environment variable should also be set to 1 to assert that loaded file is really the underlying system.

    -

    Loading a XML topology is usually much faster than querying multiple files or calling multiple functions of the operating system. It is also possible to manipulate such XML files with the C programming interface, and the import/export may also be directed to memory buffer (that may for instance be transmitted between applications through a package). See also Importing and exporting topologies from/to XML files.

    -
    Note
    The environment variable HWLOC_THISSYSTEM_ALLOWED_RESOURCES may be used to load a XML topology that contains the entire machine and restrict it to the part that is actually available to the current process (e.g. when Linux Cgroup/Cpuset are used to restrict the set of resources). See Environment Variables.
    -

    Shared-memory topologies consist in one process exposing its topology in a shared-memory buffer so that other processes (running on the same machine) may use it directly. This has the advantage of reducing the memory footprint since a single topology is stored in physical memory for multiple processes. However, it requires all processes to map this shared-memory buffer at the same virtual address, which may be difficult in some cases. This API is described in Sharing topologies between processes.

    -

    -How many topologies may I use in my program?

    -

    hwloc lets you manipulate multiple topologies at the same time. However, these topologies consume memory and system resources (for instance file descriptors) until they are destroyed. It is therefore discouraged to open the same topology multiple times.

    -

    Sharing a single topology between threads is easy (see Thread Safety) since the vast majority of accesses are read-only.

    -

    If multiple topologies of different (but similar) nodes are needed in your program, have a look at How to avoid memory waste when manipulating multiple similar topologies?.

    -

    -How to avoid memory waste when manipulating multiple similar topologies?

    -

    hwloc does not share information between topologies. If multiple similar topologies are loaded in memory, for instance the topologies of different identical nodes of a cluster, lots of information will be duplicated.

    -

    hwloc/diff.h (see also Topology differences) offers the ability to compute topology differences, apply or unapply them, or export/import to/from XML. However, this feature is limited to basic differences such as attribute changes. It does not support complex modifications such as adding or removing some objects.

    -

    -How do I annotate the topology with private notes?

    -

    Each hwloc object contains a userdata field that may be used by applications to store private pointers. This field is only valid during the lifetime of these container object and topology. It becomes invalid as soon the topology is destroyed, or as soon as the object disappears, for instance when restricting the topology. The userdata field is not exported/imported to/from XML by default since hwloc does not know what it contains. This behavior may be changed by specifying application-specific callbacks with hwloc_topology_set_userdata_export_callback() and hwloc_topology_set_userdata_import_callback().

    -

    Each object may also contain some info attributes (key name and value) that are setup by hwloc during discovery and that may be extended by the user with hwloc_obj_add_info() (see also Object attributes). Contrary to the userdata field which is unique, multiple info attributes may exist for each object, even with the same name. These attributes are always exported to XML. However, only character strings may be used as key names and values.

    -

    It is also possible to insert Misc objects with a custom name anywhere as a leaf of the topology (see Miscellaneous objects). And Misc objects may have their own userdata and info attributes just like any other object.

    -

    The hwloc-annotate command-line tool may be used for adding Misc objects and info attributes.

    -

    There is also a topology-specific userdata pointer that can be used to recognize different topologies by storing a custom pointer. It may be manipulated with hwloc_topology_set_userdata() and hwloc_topology_get_userdata().

    -

    -How do I create a custom heterogeneous and asymmetric topology?

    -

    Synthetic topologies (see Synthetic topologies) allow to create custom topologies but they are always symmetric: same numbers of cores in each package, same local NUMA nodes, same shared cache, etc. To create an asymmetric topology, for instance to simulate hybrid CPUs, one may want to start from a larger symmetric topology and restrict it.
    -

    -

    Assuming we want two packages, one with 4 dual-threaded cores, and one with 8 single-threaded cores, first we create a topology with two identical packages, each with 8 dual-threaded cores: 

    $ lstopo -i "pack:2 core:8 pu:2" topo.xml
-

    Then create the bitmask representing the PUs that we wish to keep and pass it to lstopo's restrict option: 

    $ hwloc-calc -i topo.xml pack:0.core:0-3.pu:0-1 pack:1.core:0-7.pu:0
-0x555500ff
-$ lstopo -i topo.xml --restrict 0x555500ff topo2.xml
-$ mv -f topo2.xml topo.xml
-

    To mark the cores of first package as Big (power hungry) and those of second package as Little (energy efficient), define CPU kinds: 

    $ hwloc-annotate topo.xml topo.xml -- none -- cpukind $(hwloc-calc -i topo.xml pack:0) 1 0 CoreType Big
-$ hwloc-annotate topo.xml topo.xml -- none -- cpukind $(hwloc-calc -i topo.xml pack:1) 0 0 CoreType Little
-


    -

    -

    A similar method may be used for heterogeneous memory. First we specify 2 NUMA nodes per package in our synthetic description: 

    $ lstopo -i "pack:2 [numa(memory=100GB)] [numa(memory=10GB)] core:8 pu:2" topo.xml
-

    Then remove the second node of first package: 

    $ hwloc-calc -i topo.xml --nodeset node:all ~pack:0.node:1
-0x0000000e
-$ lstopo -i topo.xml --restrict nodeset=0xe topo2.xml
-$ mv -f topo2.xml topo.xml
-

    Then make one large node even bigger: 

    $ hwloc-annotate topo.xml topo.xml -- pack:0.numa:0 -- size 200GB
-

    Now we have 200GB in first package, and 100GB+10GB in second package.
    -

    -

    Next we may specify that the small NUMA node (second of second package) is HBM while the large ones are DRAM: 

    $ hwloc-annotate topo.xml topo.xml -- pack:0.numa:0 pack:1.numa:0 -- subtype DRAM
-$ hwloc-annotate topo.xml topo.xml -- pack:1.numa:1 -- subtype HBM
-

    Finally we may define memory performance attributes to specify that the HBM bandwidth (200GB/s) from local cores is higher than the DRAM bandwidth (50GB/s): 

    $ hwloc-annotate topo.xml topo.xml -- pack:0.numa:0 -- memattr Bandwidth pack:0 50000
-$ hwloc-annotate topo.xml topo.xml -- pack:1.numa:0 -- memattr Bandwidth pack:1 50000
-$ hwloc-annotate topo.xml topo.xml -- pack:1.numa:1 -- memattr Bandwidth pack:1 200000
-


    -

    -

    There is currently no way to create or modify I/O devices attached to such fake topologies. There is also no way to have some partial levels, e.g. a L3 cache in one package but not in the other.
    -

    -

    More changes may obviously be performed by manually modifying the XML export file. Simple operations such as modifying object attributes (cache size, memory size info keypairs, etc.), moving I/O subtrees, moving Misc objects, or removing objects are easy to perform.

    -

    However, modifying CPU and Memory objects requires care since cpusets and nodesets are supposed to remain consistent between parents and children. Similarly, PCI bus IDs should remain consistent between bridges and children within an I/O subtree.

    -

    -

    -

    -

    -Caveats

    -

    -Why is hwloc slow?

    -

    Building a hwloc topology on a large machine may be slow because the discovery of hundreds of hardware cores or threads takes time (especially when reading thousands of sysfs files on Linux). Ignoring some objects (for instance caches) that aren't useful to the current application may improve this overhead (see I only need binding, why should I use hwloc ?). One should also consider using XML (see I do not want hwloc to rediscover my enormous machine topology every time I rerun a process) to work around such issues.

    -

    Additionally, lstopo enables most hwloc objects and discovery flags by default so that the output topology is as precise as possible (while hwloc disables many of them by default). This includes I/O device discovery through PCI libraries as well as external libraries such as NVML. To speed up lstopo, you may disable such features with command-line options such as --no-io.

    -

    When NVIDIA GPU probing is enabled with CUDA or NVML, one should make sure that the Persistent mode is enabled (with nvidia-smi -pm 1) to avoid significant GPU initialization overhead.

    -

    When AMD GPU discovery is enabled with OpenCL and hwloc is used remotely over ssh, some spurious round-trips on the network may significantly increase the discovery time. Forcing the DISPLAY environment variable to the remote X server display (usually :0) instead of only setting the COMPUTE variable may avoid this.

    -

    Also remember that these components may be disabled at build-time with configure flags such as --disable-opencl, --disable-cuda or --disable-nvml, and at runtime with the environment variable HWLOC_COMPONENTS=-opencl,-cuda,-nvml or with hwloc_topology_set_components().

    -

    -Does hwloc require privileged access?

    -

    hwloc discovers the topology by querying the operating system. Some minor features may require privileged access to the operation system. For instance memory module discovery on Linux is reserved to root, and the entire PCI discovery on Solaris and BSDs requires access to some special files that are usually restricted to root (/dev/pci* or /devices/pci*).

    -

    To workaround this limitation, it is recommended to export the topology as a XML file generated by the administrator (with the lstopo program) and make it available to all users (see Importing and exporting topologies from/to XML files). It will offer all discovery information to any application without requiring any privileged access anymore. Only the necessary hardware characteristics will be exported, no sensitive information will be disclosed through this XML export.

    -

    This XML-based model also has the advantage of speeding up the discovery because reading a XML topology is usually much faster than querying the operating system again.

    -

    The utility hwloc-dump-hwdata is also involved in gathering privileged information at boot time and making it available to non-privileged users (note that this may require a specific SELinux MLS policy module). However, it only applies to Intel Xeon Phi processors for now (see Why do I need hwloc-dump-hwdata for memory on Intel Xeon Phi processor?). See also HWLOC_DUMPED_HWDATA_DIR in Environment Variables for details about the location of dumped files.

    -

    -What should I do when hwloc reports "operating system" warnings?

    -

    When the operating system reports invalid locality information (because of either software or hardware bugs), hwloc may fail to insert some objects in the topology because they cannot fit in the already built tree of resources. If so, hwloc will report a warning like the following. The object causing this error is ignored, the discovery continues but the resulting topology will miss some objects and may be asymmetric (see also What happens if my topology is asymmetric?).

    -
    ****************************************************************************
-* hwloc received invalid information from the operating system.
-*
-* L3 (cpuset 0x000003f0) intersects with NUMANode (P#0 cpuset 0x0000003f) without inclusion!
-* Error occurred in topology.c line 940
-*
-* Please report this error message to the hwloc user's mailing list,
-* along with the files generated by the hwloc-gather-topology script.
-*
-* hwloc will now ignore this invalid topology information and continue.
-****************************************************************************
-

    These errors are common on large AMD platforms because of BIOS and/or Linux kernel bugs causing invalid L3 cache information. In the above example, the hardware reports a L3 cache that is shared by 2 cores in the first NUMA node and 4 cores in the second NUMA node. That's wrong, it should actually be shared by all 6 cores in a single NUMA node. The resulting topology will miss some L3 caches.

    -

    If your application does not care about cache sharing, or if you do not plan to request cache-aware binding in your process launcher, you may likely ignore this error (and hide it by setting HWLOC_HIDE_ERRORS=1 in your environment).

    -

    Some platforms report similar warnings about conflicting Packages and NUMANodes.

    -

    On x86 hosts, passing HWLOC_COMPONENTS=x86 in the environment may workaround some of these issues by switching to a different way to discover the topology.

    -

    Upgrading the BIOS and/or the operating system may help. Otherwise, as explained in the message, reporting this issue to the hwloc developers (by sending the tarball that is generated by the hwloc-gather-topology script on this platform) is a good way to make sure that this is a software (operating system) or hardware bug (BIOS, etc).

    -

    See also Questions and Bugs. Opening an issue on GitHub automatically displays hints on what information you should provide when reporting such bugs.

    -

    -Why does Valgrind complain about hwloc memory leaks?

    -

    If you are debugging your application with Valgrind, you want to avoid memory leak reports that are caused by hwloc and not by your program.

    -

    hwloc itself is often checked with Valgrind to make sure it does not leak memory. However, some global variables in hwloc dependencies are never freed. For instance libz allocates its global state once at startup and never frees it so that it may be reused later. Some libxml2 global state is also never freed because hwloc does not know whether it can safely ask libxml2 to free it (the application may also be using libxml2 outside of hwloc).

    -

    These unfreed variables cause leak reports in Valgrind. hwloc installs a Valgrind suppressions file to hide them. You should pass the following command-line option to Valgrind to use it: 

      --suppressions=/path/to/hwloc-valgrind.supp
-

    -

    -

    -

    -Platform-specific

    -

    -How do I enable ROCm SMI and select which version to use?

    -

    hwloc enables ROCm SMI as soon as it finds its development headers and libraries on the system. This detection consists in looking in /opt/rocm by default. If a ROCm version was specified with --with-rocm-version=4.4.0 or in the ROCM_VERSION environment variable, then /opt/rocm-<version> is used instead. Finally, a specific installation path may be specified with --with-rocm=/path/to/rocm.

    -

    As usual, developer header and library paths may also be set through environment variables such as LIBRARY_PATH and C_INCLUDE_PATH.

    -

    To find out whether ROCm SMI was detected and enabled, look in Probe / display I/O devices at the end of the configure script output. Passing --enable-rsmi will also cause configure to fail if RSMI could not be found and enabled in hwloc.

    -

    -How do I enable CUDA and select which CUDA version to use?

    -

    hwloc enables CUDA as soon as it finds CUDA development headers and libraries on the system. This detection may be performed thanks to pkg-config but it requires hwloc to know which CUDA version to look for. This may be done by passing --with-cuda-version=11.0 to the configure script. Otherwise hwloc will also look for the CUDA_VERSION environment variable.

    -

    If pkg-config does not work, passing --with-cuda=/path/to/cuda to the configure script is another way to define the corresponding library and header paths. Finally, these paths may also be set through environment variables such as LIBRARY_PATH and C_INCLUDE_PATH.

    -

    These paths, either detected by pkg-config or given manually, will also be used to detect NVML and OpenCL libraries and enable their hwloc backends.

    -

    To find out whether CUDA was detected and enabled, look in Probe / display I/O devices at the end of the configure script output. Passing --enable-cuda will also cause configure to fail if CUDA could not be found and enabled in hwloc.

    -

    Note that --with-cuda=/nonexisting may be used to disable all dependencies that are installed by CUDA, i.e. the CUDA, NVML and NVIDIA OpenCL backends, since the given directory does not exist.

    -

    -How do I find the local MCDRAM NUMA node on Intel Xeon Phi processor?

    -

    Intel Xeon Phi processors introduced a new memory architecture by possibly having two distinct local memories: some normal memory (DDR) and some high-bandwidth on-package memory (MCDRAM). Processors can be configured in various clustering modes to have up to 4 Clusters. Moreover, each Cluster (quarter, half or whole processor) of the processor may have its own local parts of the DDR and of the MCDRAM. This memory and clustering configuration may be probed by looking at MemoryMode and ClusterMode attributes, see Hardware Platform Information and doc/examples/get-knl-modes.c in the source directory.

    -

    Starting with version 2.0, hwloc properly exposes this memory configuration. DDR and MCDRAM are attached as two memory children of the same parent, DDR first, and MCDRAM second if any. Depending on the processor configuration, that parent may be a Package, a Cache, or a Group object of type Cluster.

    -

    Hence cores may have one or two local NUMA nodes, listed by the core nodeset. An application may allocate local memory from a core by using that nodeset. The operating system will actually allocate from the DDR when possible, or fallback to the MCDRAM.

    -

    To allocate specifically on one of these memories, one should walk up the parent pointers until finding an object with some memory children. Looking at these memory children will give the DDR first, then the MCDRAM if any. Their nodeset may then be used for allocating or binding memory buffers.

    -

    One may also traverse the list of NUMA nodes until finding some whose cpuset matches the target core or PUs. The MCDRAM NUMA nodes may be identified thanks to the subtype field which is set to MCDRAM.

    -

    Command-line tools such as hwloc-bind may bind memory on the MCDRAM by using the hbm keyword. For instance, to bind on the first MCDRAM NUMA node:

    -
    $ hwloc-bind --membind --hbm numa:0 -- myprogram
-$ hwloc-bind --membind numa:0 -- myprogram
-

    -Why do I need hwloc-dump-hwdata for memory on Intel Xeon Phi processor?

    -

    Intel Xeon Phi processors may use the on-package memory (MCDRAM) as either memory or a memory-side cache (reported as a L3 cache by hwloc by default, see HWLOC_KNL_MSCACHE_L3 in Environment Variables). There are also several clustering modes that significantly affect the memory organization (see How do I find the local MCDRAM NUMA node on Intel Xeon Phi processor? for more information about these modes). Details about these are currently only available to privileged users. Without them, hwloc relies on a heuristic for guessing the modes.

    -

    The hwloc-dump-hwdata utility may be used to dump this privileged binary information into human-readable and world-accessible files that the hwloc library will later load. The utility should usually run as root once during boot, in order to update dumped information (stored under /var/run/hwloc by default) in case the MCDRAM or clustering configuration changed between reboots.

    -

    When SELinux MLS policy is enabled, a specific hwloc policy module may be required so that all users get access to the dumped files (in /var/run/hwloc by default). One may use hwloc policy files from the SELinux Reference Policy at https://github.com/TresysTechnology/refpolicy-contrib (see also the documentation at https://github.com/TresysTechnology/refpolicy/wiki/GettingStarted).

    -

    hwloc-dump-hwdata requires dmi-sysfs kernel module loaded.

    -

    The utility is currently unneeded on platforms without Intel Xeon Phi processors.

    -

    See HWLOC_DUMPED_HWDATA_DIR in Environment Variables for details about the location of dumped files.

    -

    -How do I build hwloc for BlueGene/Q?

    -

    IBM BlueGene/Q machines run a standard Linux on the login/frontend nodes and a custom CNK (Compute Node Kernel) on the compute nodes.

    -

    To discover the topology of a login/frontend node, hwloc should be configured as usual, without any BlueGene/Q-specific option.

    -

    However, one would likely rather discover the topology of the compute nodes where parallel jobs are actually running. If so, hwloc must be cross-compiled with the following configuration line: 

    ./configure --host=powerpc64-bgq-linux --disable-shared --enable-static \
-  CPPFLAGS='-I/bgsys/drivers/ppcfloor -I/bgsys/drivers/ppcfloor/spi/include/kernel/cnk/'
-

    CPPFLAGS may have to be updated if your platform headers are installed in a different directory.

    -

    -How do I build hwloc for Windows?

    -

    hwloc binary releases for Windows are available on the website download pages (as pre-built ZIPs for both 32bits and 64bits x86 platforms). However hwloc also offers several ways to build on Windows:

    -
      -
    • -The usual Unix build steps (configure, make and make install) work on the MSYS2/MinGW environment on Windows (the official hwloc binary releases are built this way). Some environment variables and options must be configured, see contrib/ci.inria.fr/job-3-mingw.sh in the hwloc repository for an example (used for nightly testing).
      • -
    • -hwloc also supports such Unix-like builds in Cygwin (environment for porting Unix code to Windows).
      • -
    • -Windows build is also possible with CMake (CMakeLists.txt available under contrib/windows-cmake/).
      • -
    • -hwloc also comes with an example of Microsoft Visual Studio solution (under contrib/windows/) that may serve as a base for custom builds.
      • -
    -

    -How to get useful topology information on NetBSD?

    -

    The NetBSD (and FreeBSD) backend uses x86-specific topology discovery (through the x86 component). This implementation requires CPU binding so as to query topology information from each individual processor. This means that hwloc cannot find any useful topology information unless user-level process binding is allowed by the NetBSD kernel. The security.models.extensions.user_set_cpu_affinity sysctl variable must be set to 1 to do so. Otherwise, only the number of processors will be detected.

    -

    -Why does binding fail on AIX?

    -

    The AIX operating system requires specific user capabilities for attaching processes to resource sets (CAP_NUMA_ATTACH). Otherwise functions such as hwloc_set_cpubind() fail (return -1 with errno set to EPERM).

    -

    This capability must also be inherited (through the additional CAP_PROPAGATE capability) if you plan to bind a process before forking another process, for instance with hwloc-bind.

    -

    These capabilities may be given by the administrator with: 

    chuser "capabilities=CAP_PROPAGATE,CAP_NUMA_ATTACH" <username>
-

    -

    -

    -

    -Compatibility between hwloc versions

    -

    -How do I handle API changes?

    -

    The hwloc interface is extended with every new major release. Any application using the hwloc API should be prepared to check at compile-time whether some features are available in the currently installed hwloc distribution.

    -

    For instance, to check whether the hwloc version is at least 2.0, you should use: 

    #include <hwloc.h>
-#if HWLOC_API_VERSION >= 0x00020000
-...
-#endif
-

    To check for the API of release X.Y.Z at build time, you may compare HWLOC_API_VERSION with (X<<16)+(Y<<8)+Z.

    -

    For supporting older releases that do not have HWLOC_OBJ_NUMANODE and HWLOC_OBJ_PACKAGE yet, you may use:

    -
    #include <hwloc.h>
-#if HWLOC_API_VERSION < 0x00010b00
-#define HWLOC_OBJ_NUMANODE HWLOC_OBJ_NODE
-#define HWLOC_OBJ_PACKAGE HWLOC_OBJ_SOCKET
-#endif
-

    Once a program is built against a hwloc library, it may also dynamically link with compatible libraries from other hwloc releases. The version of that runtime library may be queried with hwloc_get_api_version(). For instance, the following code enables the topology flag HWLOC_TOPOLOGY_FLAG_NO_DISTANCES when compiling on hwloc 2.8 or later, but it disables it at runtime if running on an older hwloc (otherwise hwloc_topology_set_flags() would fail).

    -
    unsigned long topology_flags = ...; /* wanted flags that were supported before 2.8 */
-#if HWLOC_API_VERSION >= 0x20800
-if (hwloc_get_api_version() >= 0x20800)
-  topology_flags |= HWLOC_TOPOLOGY_FLAG_NO_DISTANCES; /* wanted flags only supported in 2.8+ */
-#endif
-hwloc_topology_set_flags(topology, topology_flags);
-

    See also How do I handle ABI breaks? for using hwloc_get_api_version() for testing ABI compatibility.

    -

    -What is the difference between API and library version numbers?

    -

    HWLOC_API_VERSION is the version of the API. It changes when functions are added, modified, etc. However it does not necessarily change from one release to another. For instance, two releases of the same series (e.g. 2.0.3 and 2.0.4) usually have the same HWLOC_API_VERSION (0x00020000). However their HWLOC_VERSION strings are different ("2.0.3" and "2.0.4" respectively).

    -

    -How do I handle ABI breaks?

    -

    The hwloc interface was deeply modified in release 2.0 to fix several issues of the 1.x interface (see Upgrading to the hwloc 2.0 API and the NEWS file in the source directory for details). The ABI was broken, which means applications must be recompiled against the new 2.0 interface.

    -

    To check that you are not mixing old/recent headers with a recent/old runtime library, check the major revision number in the API version: 

    #include <hwloc.h>
-  unsigned version = hwloc_get_api_version();
-  if ((version >> 16) != (HWLOC_API_VERSION >> 16)) {
-    fprintf(stderr,
-           "%s compiled for hwloc API 0x%x but running on library API 0x%x.\n"
-           "You may need to point LD_LIBRARY_PATH to the right hwloc library.\n"
-           "Aborting since the new ABI is not backward compatible.\n",
-           callname, HWLOC_API_VERSION, version);
-    exit(EXIT_FAILURE);
-  }
-

    To specifically detect v2.0 issues: 

    #include <hwloc.h>
-#if HWLOC_API_VERSION >= 0x00020000
-  /* headers are recent */
-  if (hwloc_get_api_version() < 0x20000)
-    ... error out, the hwloc runtime library is older than 2.0 ...
-#else
-  /* headers are pre-2.0 */
-  if (hwloc_get_api_version() >= 0x20000)
-    ... error out, the hwloc runtime library is more recent than 2.0 ...
-#endif
-

    In theory, library sonames prevent linking with incompatible libraries. However custom hwloc installations or improperly configured build environments may still lead to such issues. Hence running one of the above (cheap) checks before initializing hwloc topology may be useful.

    -

    -Are XML topology files compatible between hwloc releases?

    -

    XML topology files are forward-compatible: a XML file may be loaded by a hwloc library that is more recent than the hwloc release that exported that file.

    -

    However, hwloc XMLs are not always backward-compatible: Topologies exported by hwloc 2.x cannot be imported by 1.x by default (see XML changes for working around such issues). There are also some corner cases where backward compatibility is not guaranteed because of changes between major releases (for instance 1.11 XMLs could not be imported in 1.10).

    -

    XMLs are exchanged at runtime between some components of the HPC software stack (for instance the resource managers and MPI processes). Building all these components on the same (cluster-wide) hwloc installation is a good way to avoid such incompatibilities.

    -

    -Are synthetic strings compatible between hwloc releases?

    -

    Synthetic strings (see Synthetic topologies) are forward-compatible: a synthetic string generated by a release may be imported by future hwloc libraries.

    -

    However they are often not backward-compatible because new details may have been added to synthetic descriptions in recent releases. Some flags may be given to hwloc_topology_export_synthetic() to avoid such details and stay backward compatible.

    -

    -Is it possible to share a shared-memory topology between different hwloc releases?

    -

    Shared-memory topologies (see Sharing topologies between processes) have strong requirements on compatibility between hwloc libraries. Adopting a shared-memory topology fails if it was exported by a non-compatible hwloc release. Releases with same major revision are usually compatible (e.g. hwloc 2.0.4 may adopt a topology exported by 2.0.3) but different major revisions may be incompatible (e.g. hwloc 2.1.0 cannot adopt from 2.0.x).

    -

    Topologies are shared at runtime between some components of the HPC software stack (for instance the resource managers and MPI processes). Building all these components on the same (system-wide) hwloc installation is a good way to avoid such incompatibilities.

    -
    -
    - - - - - - -
    -
    -
    -
    Upgrading to the hwloc 2.0 API
    -
    -
    -

    -

    -

    -

    See Compatibility between hwloc versions for detecting the hwloc version that you are compiling and/or running against.

    -

    -

    -

    -

    -New Organization of NUMA nodes and Memory

    -

    -Memory children

    -

    In hwloc v1.x, NUMA nodes were inside the tree, for instance Packages contained 2 NUMA nodes which contained a L3 and several cache.

    -

    Starting with hwloc v2.0, NUMA nodes are not in the main tree anymore. They are attached under objects as Memory Children on the side of normal children. This memory children list starts at obj->memory_first_child and its size is obj->memory_arity. Hence there can now exist two local NUMA nodes, for instance on Intel Xeon Phi processors.

    -

    The normal list of children (starting at obj->first_child, ending at obj->last_child, of size obj->arity, and available as the array obj->children) now only contains CPU-side objects: PUs, Cores, Packages, Caches, Groups, Machine and System. hwloc_get_next_child() may still be used to iterate over all children of all lists.

    -

    Hence the CPU-side hierarchy is built using normal children, while memory is attached to that hierarchy depending on its affinity.

    -

    -Examples

    -
      -
    • -

      a UMA machine with 2 packages and a single NUMA node is now modeled as a "Machine" object with two "Package" children and one "NUMANode" memory children (displayed first in lstopo below): 

      Machine (1024MB total)
-  NUMANode L#0 (P#0 1024MB)
-  Package L#0
-    Core L#0 + PU L#0 (P#0)
-    Core L#1 + PU L#1 (P#1)
-  Package L#1
-    Core L#2 + PU L#2 (P#2)
-    Core L#3 + PU L#3 (P#3)
-

      -
      • -
    • -

      a machine with 2 packages with one NUMA node and 2 cores in each is now: 

      Machine (2048MB total)
-  Package L#0
-    NUMANode L#0 (P#0 1024MB)
-    Core L#0 + PU L#0 (P#0)
-    Core L#1 + PU L#1 (P#1)
-  Package L#1
-    NUMANode L#1 (P#1 1024MB)
-    Core L#2 + PU L#2 (P#2)
-    Core L#3 + PU L#3 (P#3)
-

      -
      • -
    • -

      if there are two NUMA nodes per package, a Group object may be added to keep cores together with their local NUMA node: 

      Machine (4096MB total)
-  Package L#0
-    Group0 L#0
-      NUMANode L#0 (P#0 1024MB)
-      Core L#0 + PU L#0 (P#0)
-      Core L#1 + PU L#1 (P#1)
-    Group0 L#1
-      NUMANode L#1 (P#1 1024MB)
-      Core L#2 + PU L#2 (P#2)
-      Core L#3 + PU L#3 (P#3)
-  Package L#1
-    [...]
-

      -
      • -
    • -if the platform has L3 caches whose localities are identical to NUMA nodes, Groups aren't needed: 
      Machine (4096MB total)
-  Package L#0
-    L3 L#0 (16MB)
-      NUMANode L#0 (P#0 1024MB)
-      Core L#0 + PU L#0 (P#0)
-      Core L#1 + PU L#1 (P#1)
-    L3 L#1 (16MB)
-      NUMANode L#1 (P#1 1024MB)
-      Core L#2 + PU L#2 (P#2)
-      Core L#3 + PU L#3 (P#3)
-  Package L#1
-    [...]
-
      • -
    -

    -NUMA level and depth

    -

    NUMA nodes are not in "main" tree of normal objects anymore. Hence, they don't have a meaningful depth anymore (like I/O and Misc objects). They have a virtual (negative) depth (HWLOC_TYPE_DEPTH_NUMANODE) so that functions manipulating depths and level still work, and so that we can still iterate over the level of NUMA nodes just like for any other level.

    -

    For instance we can still use lines such as 

    int depth = hwloc_get_type_depth(topology, HWLOC_OBJ_NUMANODE);
-hwloc_obj_t obj = hwloc_get_obj_by_type(topology, HWLOC_OBJ_NUMANODE, 4);
-hwloc_obj_t node = hwloc_get_next_obj_by_depth(topology, HWLOC_TYPE_DEPTH_NUMANODE, prev);
-

    The NUMA depth should not be compared with others. An unmodified code that still compares NUMA and Package depths (to find out whether Packages contain NUMA or the contrary) would now always assume Packages contain NUMA (because the NUMA depth is negative).

    -

    However, the depth of the Normal parents of NUMA nodes may be used instead. In the last example above, NUMA nodes are attached to L3 caches, hence one may compare the depth of Packages and L3 to find out that NUMA nodes are contained in Packages. This depth of parents may be retrieved with hwloc_get_memory_parents_depth(). However, this function may return HWLOC_TYPE_DEPTH_MULTIPLE on future platforms if NUMA nodes are attached to different levels.

    -

    -Finding Local NUMA nodes and looking at Children and Parents

    -

    Applications that walked up/down to find NUMANode parent/children must now be updated. Instead of looking directly for a NUMA node, one should now look for an object that has some memory children. NUMA node(s) will be attached there. For instance, when looking for a NUMA node above a given core core: 

    hwloc_obj_t parent = core->parent;
-while (parent && !parent->memory_arity)
-  parent = parent->parent; /* no memory child, walk up */
-if (parent)
-  /* use parent->memory_first_child (and its siblings if there are multiple local NUMA nodes) */
-

    The list of local NUMA nodes (usually a single one) is also described by the nodeset attribute of each object (which contains the physical indexes of these nodes). Iterating over the NUMA level is also an easy way to find local NUMA nodes: 

    hwloc_obj_t tmp = NULL;
-while ((tmp = hwloc_get_next_obj_by_type(topology, HWLOC_OBJ_NUMANODE, tmp)) != NULL) {
-  if (hwloc_bitmap_isset(obj->nodeset, tmp->os_index))
-    /* tmp is a NUMA node local to obj, use it */
-}
-

    Similarly finding objects that are close to a given NUMA nodes should be updated too. Instead of looking at the NUMA node parents/children, one should now find a Normal parent above that NUMA node, and then look at its parents/children as usual: 

    hwloc_obj_t tmp = obj->parent;
-while (hwloc_obj_type_is_memory(tmp))
-  tmp = tmp->parent;
-/* now use tmp instead of obj */
-

    To avoid such hwloc v2.x-specific and NUMA-specific cases in the code, a generic lookup for any kind of object, including NUMA nodes, might also be implemented by iterating over a level. For instance finding an object of type type which either contains or is included in object obj can be performed by traversing the level of that type and comparing CPU sets: 

    hwloc_obj_t tmp = NULL;
-while ((tmp = hwloc_get_next_obj_by_type(topology, type, tmp)) != NULL) {
-  if (hwloc_bitmap_intersects(tmp->cpuset, obj->cpuset))
-    /* tmp matches, use it */
-}
-

    This generic lookup works whenever type or obj are Normal or Memory objects since both have CPU sets. Moreover, it is compatible with the hwloc v1.x API.

    -

    -

    -

    -

    -4 Kinds of Objects and Children

    -

    -I/O and Misc children

    -

    I/O children are not in the main object children list anymore either. They are in the list starting at obj->io_first_child and its size is obj->io_arity.

    -

    Misc children are not in the main object children list anymore. They are in the list starting at obj->misc_first_child and its size is obj->misc_arity.

    -

    See hwloc_obj for details about children lists.

    -

    hwloc_get_next_child() may still be used to iterate over all children of all lists.

    -

    -Kinds of objects

    -

    Given the above, objects may now be of 4 kinds:

      -
    • -Normal (everything not listed below, including Machine, Package, Core, PU, CPU Caches, etc);
      • -
    • -Memory (currently NUMA nodes or Memory-side Caches), attached to parents as Memory children;
      • -
    • -I/O (Bridges, PCI and OS devices), attached to parents as I/O children;
      • -
    • -Misc objects, attached to parents as Misc children.
      • -
    -

    See hwloc_obj for details about children lists.

    -

    For a given object type, the kind may be found with hwloc_obj_type_is_normal(), hwloc_obj_type_is_memory(), hwloc_obj_type_is_normal(), or comparing with HWLOC_OBJ_MISC.

    -

    Normal and Memory objects have (non-NULL) CPU sets and nodesets, while I/O and Misc objects don't have any sets (they are NULL).

    -

    -

    -

    -

    -HWLOC_OBJ_CACHE replaced

    -

    Instead of a single HWLOC_OBJ_CACHE, there are now 8 types HWLOC_OBJ_L1CACHE, ..., HWLOC_OBJ_L5CACHE, HWLOC_OBJ_L1ICACHE, ..., HWLOC_OBJ_L3ICACHE.

    -

    Cache object attributes are unchanged.

    -

    hwloc_get_cache_type_depth() is not needed to disambiguate cache types anymore since new types can be passed to hwloc_get_type_depth() without ever getting HWLOC_TYPE_DEPTH_MULTIPLE anymore.

    -

    hwloc_obj_type_is_cache(), hwloc_obj_type_is_dcache() and hwloc_obj_type_is_icache() may be used to check whether a given type is a cache, data/unified cache or instruction cache.

    -

    -

    -

    -

    -allowed_cpuset and allowed_nodeset only in the main topology

    -

    Objects do not have allowed_cpuset and allowed_nodeset anymore. They are only available for the entire topology using hwloc_topology_get_allowed_cpuset() and hwloc_topology_get_allowed_nodeset().

    -

    As usual, those are only needed when the INCLUDE_DISALLOWED topology flag is given, which means disallowed objects are kept in the topology. If so, one may find out whether some PUs inside an object is allowed by checking 

    hwloc_bitmap_intersects(obj->cpuset, hwloc_topology_get_allowed_cpuset(topology))
-

    Replace cpusets with nodesets for NUMA nodes. To find out which ones, replace intersects() with and() to get the actual intersection.

    -

    -

    -

    -

    -Object depths are now signed int

    -

    obj->depth as well as depths given to functions such as hwloc_get_obj_by_depth() or returned by hwloc_topology_get_depth() are now signed int.

    -

    Other depth such as cache-specific depth attribute are still unsigned.

    -

    -

    -

    -

    -Memory attributes become NUMANode-specific

    -

    Memory attributes such as obj->memory.local_memory are now only available in NUMANode-specific attributes in obj->attr->numanode.local_memory.

    -

    obj->memory.total_memory is available in all objects as obj->total_memory.

    -

    See hwloc_obj_attr_u::hwloc_numanode_attr_s and hwloc_obj for details.

    -

    -

    -

    -

    -Topology configuration changes

    -

    The old ignoring API as well as several configuration flags are replaced with the new filtering API, see hwloc_topology_set_type_filter() and its variants, and hwloc_type_filter_e for details.

    -
      -
    • -

      hwloc_topology_ignore_type(), hwloc_topology_ignore_type_keep_structure() and hwloc_topology_ignore_all_keep_structure() are respectively superseded by 

      hwloc_topology_set_type_filter(topology, type, HWLOC_TYPE_FILTER_KEEP_NONE);
-hwloc_topology_set_type_filter(topology, type, HWLOC_TYPE_FILTER_KEEP_STRUCTURE);
-hwloc_topology_set_all_types_filter(topology, HWLOC_TYPE_FILTER_KEEP_STRUCTURE);
-

      Also, the meaning of KEEP_STRUCTURE has changed (only entire levels may be ignored, instead of single objects), the old behavior is not available anymore.

      -

      -
      • -
    • -

      HWLOC_TOPOLOGY_FLAG_ICACHES is superseded by 

      hwloc_topology_set_icache_types_filter(topology, HWLOC_TYPE_FILTER_KEEP_ALL);
-

      -
      • -
    • -

      HWLOC_TOPOLOGY_FLAG_WHOLE_IO, HWLOC_TOPOLOGY_FLAG_IO_DEVICES and HWLOC_TOPOLOGY_FLAG_IO_BRIDGES replaced.

      -

      To keep all I/O devices (PCI, Bridges, and OS devices), use: 

      hwloc_topology_set_io_types_filter(topology, HWLOC_TYPE_FILTER_KEEP_ALL);
-

      To only keep important devices (Bridges with children, common PCI devices and OS devices): 

      hwloc_topology_set_io_types_filter(topology, HWLOC_TYPE_FILTER_KEEP_IMPORTANT);
-

      -
      • -
    -

    -

    -

    -

    -XML changes

    -

    2.0 XML files are not compatible with 1.x

    -

    2.0 can load 1.x files, but only NUMA distances are imported. Other distance matrices are ignored (they were never used by default anyway).

    -

    2.0 can export 1.x-compatible files, but only distances attached to the root object are exported (i.e. distances that cover the entire machine). Other distance matrices are dropped (they were never used by default anyway).

    -

    Users are advised to negociate hwloc versions between exporter and importer: If the importer isn't 2.x, the exporter should export to 1.x. Otherwise, things should work by default.

    -

    Hence hwloc_topology_export_xml() and hwloc_topology_export_xmlbuffer() have a new flags argument. to force a hwloc-1.x-compatible XML export.

      -
    • -If both always support 2.0, don't pass any flag.
      • -
    • -When the importer uses hwloc 1.x, export with HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1. Otherwise the importer will fail to import.
      • -
    • -When the exporter uses hwloc 1.x, it cannot pass any flag, and a 2.0 importer can import without problem.
      • -
    -
    #if HWLOC_API_VERSION >= 0x20000
-   if (need 1.x compatible XML export)
-      hwloc_topology_export_xml(...., HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1);
-   else /* need 2.x compatible XML export */
-      hwloc_topology_export_xml(...., 0);
-#else
-   hwloc_topology_export_xml(....);
-#endif
-

    Additionally, hwloc_topology_diff_load_xml(), hwloc_topology_diff_load_xmlbuffer(), hwloc_topology_diff_export_xml(), hwloc_topology_diff_export_xmlbuffer() and hwloc_topology_diff_destroy() lost the topology argument: The first argument (topology) isn't needed anymore.

    -

    -

    -

    -

    -Distances API totally rewritten

    -

    The new distances API is in hwloc/distances.h.

    -

    Distances are not accessible directly from objects anymore. One should first call hwloc_distances_get() (or a variant) to retrieve distances (possibly with one call to get the number of available distances structures, and another call to actually get them). Then it may consult these structures, and finally release them.

    -

    The set of object involved in a distances structure is specified by an array of objects, it may not always cover the entire machine or so.

    -

    -

    -

    -

    -Return values of functions

    -

    Bitmap functions (and a couple other functions) can return errors (in theory).

    -

    Most bitmap functions may have to reallocate the internal bitmap storage. In v1.x, they would silently crash if realloc failed. In v2.0, they now return an int that can be negative on error. However, the preallocated storage is 512 bits, hence realloc will not even be used unless you run hwloc on machines with larger PU or NUMAnode indexes.

    -

    hwloc_obj_add_info(), hwloc_cpuset_from_nodeset() and hwloc_cpuset_from_nodeset() also return an int, which would be -1 in case of allocation errors.

    -

    -

    -

    -

    -Misc API changes

    - -

    -

    -

    -

    -API removals and deprecations

    -
      -
    • -

      HWLOC_OBJ_SYSTEM removed: The root object is always HWLOC_OBJ_MACHINE

      -

      -
      • -
    • -

      _membind_nodeset() memory binding interfaces deprecated: One should use the variant without _nodeset suffix and pass the HWLOC_MEMBIND_BYNODESET flag.

      -

      -
      • -
    • -

      HWLOC_MEMBIND_REPLICATE removed: no supported operating system supports it anymore.

      -

      -
      • -
    • -

      hwloc_obj_snprintf() removed because it was long-deprecated by hwloc_obj_type_snprintf() and hwloc_obj_attr_snprintf().

      -

      -
      • -
    • -

      hwloc_obj_type_sscanf() deprecated, hwloc_obj_type_of_string() removed.

      -

      -
      • -
    • -

      hwloc_cpuset_from/to_nodeset_strict() deprecated: Now useless since all topologies are NUMA. Use the variant without the _strict suffix

      -

      -
      • -
    • -

      hwloc_distribute() and hwloc_distributev() removed, deprecated by hwloc_distrib().

      -

      -
      • -
    • -

      The Custom interface (hwloc_topology_set_custom(), etc.) was removed, as well as the corresponding command-line tools (hwloc-assembler, etc.). Topologies always start with object with valid cpusets and nodesets.

      -

      -
      • -
    • -

      obj->online_cpuset removed: Offline PUs are simply listed in the complete_cpuset as previously.

      -

      -
      • -
    • -

      obj->os_level removed.

      -

      -
      • -
    -
    -
    - - - - - - -
    -
    -
    -
    Network Locality (netloc)
    -
    -
    -

    -

    -

    -

    Portable abstraction of network topologies for high-performance computing.

    -

    The netloc documentation spans of these sections:

    -

    -

    -

    -

    -Netloc Summary

    -

    The Portable Network Locality (netloc) software package provides network topology discovery tools, and an abstract representation of those networks topologies for a range of network types and configurations. It is provided as a companion to the Portable Hardware Locality (hwloc) package. These two software packages work together to provide a comprehensive view of the HPC system topology, spanning from the processor cores in one server to the cores in another - including the complex network(s) in between.

    -

    Towards this end, netloc is divided into two sets of components. The first tools are for the admin to extract the information about the topology of the machines with topology discovery tools for each network type and discovery technique (called readers). The second set of tools is for the user to exploit the collected information: to display the topology or create a topology-aware mapping of the processes of an application.

    -
    - -
    -

    -

    -

    -

    -Supported Networks

    -

    For now, only InfiniBand (See Setup) is supported, but it is planned to be extended it very soon.

    -

    -

    -

    -

    -Netloc Installation

    -

    The generic installation procedure for both hwloc and netloc is described in Installation.

    -

    Note that netloc is currently not supported on as many platforms as the original hwloc project. netloc is enabled by default when supported, or can be disabled by passing --disable-netloc to the configure command-line.

    -

    -

    -

    -

    -Setup

    -

    To use Netloc tools, we need two steps. The first step consists in getting information about network directly from tools distributed by manufacturers. For Infiniband, for instance, this operation needs privileges to access to the network device. For this step we have wrappers in Netloc that will call the right tools with the right options.

    -

    The second step will transform the raw files generated by manufacturer tools, into files in a format readable by Netloc tools, and that will not depend on network technologies.

    -

    To be clear, let's take an example with Infiniband. This first step is handled by netloc_ib_gather_raw that will call ibnetdiscover and ibroutes tools to generate the necessary raw data files. The step has to be run by an administrator, since the Infiniband tools need to access to the network device.

    -
    shell$ netloc_ib_gather_raw --help
-Usage: netloc_ib_gather_raw [options] <outdir>
-  Dumps topology information to <outdir>/ib-raw/
-  Subnets are guessed from the <outdir>/hwloc/ directory where
-  the hwloc XML exports of some nodes are stored.
-Options:
- --sudo
-    Pass sudo to internal ibnetdiscover and ibroute invocations.
-    Useful when the entire script cannot run as root.
- --hwloc-dir <dir>
-    Use <dir> instead of <outdir>/hwloc/ for hwloc XML exports.
- --force-subnet [<subnet>:]<board>:<port> to force the discovery
-    Do not guess subnets from hwloc XML exports.
-    Force discovery on local board <board> port <port>
-    and optionally force the subnet id <subnet>
-    instead of reading it from the first GID.
-    Examples: --force-subnet mlx4_0:1
-              --force-subnet fe80:0000:0000:0000:mlx4_0:1
- --ibnetdiscover /path/to/ibnetdiscover
- --ibroute /path/to/ibroute
-    Specify exact location of programs. Default is /usr/bin/<program>
- --sleep <n>
-    Sleep for <n> seconds between invocations of programs probing the network
- --ignore-errors
-    Ignore errors from ibnetdiscover and ibroute, assume their outputs are ok
- --force -f
-    Always rediscover to overwrite existing files without asking
- --verbose -v
-    Add verbose messages
- --dry-run
-    Do not actually run programs or modify anything
- --help -h
-    Show this help
-
-shell$ ./netloc_ib_gather_raw /home/netloc/data
-WARNING: Not running as root.
-Using /home/netloc/data/hwloc as hwloc lstopo XML directory.
-
-Exporting local node hwloc XML...
-  Running lstopo-no-graphics...
-
-Found 1 subnets in hwloc directory:
- Subnet fe80:0000:0000:0000 is locally accessible from board qib0 port 1.
-
-Looking at fe80:0000:0000:0000 (through local board qib0 port 1)...
- Running ibnetdiscover...
- Getting routes...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L112' LID 18...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L108' LID 20...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L102' LID 23...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L104' LID 25...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L106' LID 24...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L114' LID 22...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L116' LID 21...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L109' LID 12...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L111' LID 11...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L107' LID 13...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L103' LID 17...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L105' LID 16...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L113' LID 15...
-

    The second step, that can be done by a regular user, is done by the tool netloc_ib_extract_dats.

    -
    shell$ netloc_ib_extract_dats --help
-Usage: netloc_ib_extract_dats <path to input raw data files> <output path> [--hwloc-dir
-<hwloc xml path>]
-        hwloc-dir can be an absolute path or a relative path from output path
-
-shell$ netloc_ib_extract_dats /home/netloc/data/ib-raw /home/netloc/data/netloc \
-  --hwloc-dir ../hwloc
-Read subnet: fe80:0000:0000:0000
-2 partitions found
-        'node'
-        'admin'
-

    -

    -

    -

    -Topology display

    -

    Netloc provides a tool, netloc_draw.html, that displays a topology in a web browser, by using a JSON file.

    -

    -Generate the JSON file

    -

    In order to display a topology, Netloc needs to generate a JSON file corresponding to a topology. For this operation, the user must run netloc_draw_to_json.

    -
    shell$ netloc_draw_to_json --help
-Usage: netloc_draw_to_json <path to topology directory>
-
-shell$ netloc_draw_to_json /home/netloc/data/netloc
-

    The netloc_draw_to_json command will write a JSON file for each topology file found in the input directory. The output files, written also in the input directory, can be open by netloc_draw.html in a web browser.

    -

    -Using netloc_draw

    -

    Once the JSON file is opened, the rendering is generated by the Javascript vis library for computing the position of the nodes. From the interface, it is possible to search for a specific node, to color the nodes, to expand merged switches, to show statistics, to export as an image... The user can interact with the nodes by moving them. For now, there are bugs and other nodes might move too.

    -

    The placement of the nodes is done statically if the topology is detected as a tree. If not, vis.js will use physics to find good positions, and it can be very time consuming.

    -
    - -
    -
    -
    - - - - - - -
    -
    -
    -
    Netloc with Scotch
    -
    -
    -

    -

    -

    -

    Scotch is a toolbox for graph partitioning [XXX], that can do mapping between a communication graph and an architecture. Netloc interfaces with Scotch, by getting the topology of the machine and building the Scotch architecture. It is also possible to directly build a mapping file that can be given to mpirun.

    -

    -

    -

    -

    -Introduction

    -

    Scotch is able to deal architectures to represent the topology of a complete machine. Scotch handles several types of topologies: complete graphs, hypercubes, fat trees, meshes, torus, and random graphs. Moreover, Scotch is able to manage parts of architectures that are called sub-architectures. Thus, from a complete architecture, we can create a sub-architecture that will represent the available resources of the complete machine.

    -

    -

    -

    -

    -Setup

    -

    The first step in order to use Netloc tools is to discover the network. For this task, we provide tools called netloc_gather that are wrappers to the dedicated tools provided by the manufacturer of the network, that generate the raw data given by the devices. This task needs privileges to access to the network devices. Once, this task is completed, the raw data is converted in a generic format independent to the fabric by extract_dats. Figure 1 shows how the different modules of Netloc are linked, and what are the tools provided by Netloc.

    -

    -

    -

    -

    -Tools and API

    -

    When the machine is discovered and all the needed files are generated as seen previously, a user can call the netlocscotch functions from the API and interact with Scotch.

    -

    -Build Scotch architectures

    -

    Netloc provides a function to export the built topology into the Scotch format. That will give the possibility to the user to play with the topology in Scotch. Since Netloc matches the discovered topology with known topologies, the Scotch architecture won’t be random graphs but known topologies also in Scotch that will lead to optimized graph algorithms. This function is called netlocscotch_build_arch.

    -

    When the network topology is a tree, the topology converted by netlocscotch is the complete topology of the machine containing intranode topologies from hwloc. In this case, merging the two levels results in a bigger tree. For other network topologies, the global graph created for Scotch is a generic graph since it not not (at this moment) possible to create nested known architectures.

    -

    -Build Scotch sub-architectures

    -

    Most of the time, the user does not have access to the complete machine. He uses a resource manager to run his application and he will gain access only to a set of nodes. In this case getting the Scotch architecture of the complete machine is not relevant. Fortunately, Netloc is also able to build a Scotch sub-architecture that will contain only the available nodes. For this operation the user needs to run a specific program, netloc_get_resources, that will record in a file, the lists of available nodes and available cores by using MPI and hwloc. From this file, the function netlocscotch_build_subarch will build the Scotch sub-architecture.

    -

    -Mapping of processes

    -

    A main goal in having all these data about the network topology, especially in Scotch structures, is to help the process placement. For that, we use the mapping of a process graph to the architecture provided by Scotch. As we have seen previously, Netloc is able to detect the structure of the topology and will build the adapted Scotch architecture that will be more efficient than a random structure.

    -

    In case, the network topology is not a tree, netlocscotch converts the complete topology into a generic graph. The drawback in that is the Scotch graph algorithms are less efficient. To overcome that, netlocscotch does two steps of mapping: first it maps the processes to the nodes, and then for each node maps the processes to the cores. We have to conduct tests to check if the method gives better results than using a generic graph directly.

    -

    The other input needed in Scotch is the process graph. Since we want to optimize the placement to decrease the communication time, a good metric for building the application graph is the amount of communications between all pairs of processes. Studies still have to be done to choose, in the most efficient way, what we take into account to define the amount of communications between the number of messages, the size of messages... This information will be transformed into a process graph.

    -

    Once we have a good mapping computed by Scotch, we can give it to the user, or Netloc can even generate the corresponding rank file useful to MPI.

    -
    -
    - - - - - - -
    -
    -
    -
    Data Structures
    -
    -
    -
    Here are the data structures with brief descriptions:
    -
    [detail level 123]
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     Chwloc_backendDiscovery backend structure
     Chwloc_cl_device_topology_amd
     Chwloc_componentGeneric component structure
     Chwloc_disc_componentDiscovery component structure
     Chwloc_disc_statusDiscovery status structure
     Chwloc_distances_sMatrix of distances between a set of objects
     Chwloc_info_sObject info
     ▼Chwloc_locationWhere to measure attributes from
     Chwloc_location_uActual location
     Chwloc_objStructure of a topology object
     ▼Chwloc_obj_attr_uObject type-specific Attributes
     Chwloc_bridge_attr_sBridge specific Object Attributes
     Chwloc_cache_attr_sCache-specific Object Attributes
     Chwloc_group_attr_sGroup-specific Object Attributes
     ▼Chwloc_numanode_attr_sNUMA node-specific Object Attributes
     Chwloc_memory_page_type_sArray of local memory page types, NULL if no local memory and page_types is 0
     Chwloc_osdev_attr_sOS Device specific Object Attributes
     Chwloc_pcidev_attr_sPCI Device specific Object Attributes
     Chwloc_topology_cpubind_supportFlags describing actual PU binding support for this topology
     ▼Chwloc_topology_diff_obj_attr_uOne object attribute difference
     Chwloc_topology_diff_obj_attr_generic_s
     Chwloc_topology_diff_obj_attr_string_sString attribute modification with an optional name
     Chwloc_topology_diff_obj_attr_uint64_sInteger attribute modification with an optional index
     ▼Chwloc_topology_diff_uOne element of a difference list between two topologies
     Chwloc_topology_diff_generic_s
     Chwloc_topology_diff_obj_attr_s
     Chwloc_topology_diff_too_complex_s
     Chwloc_topology_discovery_supportFlags describing actual discovery support for this topology
     Chwloc_topology_membind_supportFlags describing actual memory binding support for this topology
     Chwloc_topology_misc_supportFlags describing miscellaneous features
     Chwloc_topology_supportSet of flags describing actual support for this topology
    -
    -
    - - - - - - - -
    -
    -
    Data Structure Index
    -
    -
    -
    H
    -
    -
    -
    H
    -
    hwloc_backend
    hwloc_obj_attr_u::hwloc_bridge_attr_s
    hwloc_obj_attr_u::hwloc_cache_attr_s
    hwloc_cl_device_topology_amd
    hwloc_component
    hwloc_disc_component
    hwloc_disc_status
    hwloc_distances_s
    hwloc_obj_attr_u::hwloc_group_attr_s
    hwloc_info_s
    hwloc_location
    hwloc_location::hwloc_location_u
    hwloc_obj_attr_u::hwloc_numanode_attr_s::hwloc_memory_page_type_s
    hwloc_obj_attr_u::hwloc_numanode_attr_s
    hwloc_obj
    hwloc_obj_attr_u
    hwloc_obj_attr_u::hwloc_osdev_attr_s
    hwloc_obj_attr_u::hwloc_pcidev_attr_s
    hwloc_topology_cpubind_support
    hwloc_topology_diff_u::hwloc_topology_diff_generic_s
    hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_generic_s
    hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s
    hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s
    hwloc_topology_diff_obj_attr_u
    hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s
    hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s
    hwloc_topology_diff_u
    hwloc_topology_discovery_support
    hwloc_topology_membind_support
    hwloc_topology_misc_support
    hwloc_topology_support
    -
    -
    - - - - - - - - -
    -
    -
    hwloc Directory Reference
    -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

    -Files

    file  bitmap.h [code]
     
    file  cpukinds.h [code]
     
    file  cuda.h [code]
     
    file  cudart.h [code]
     
    file  diff.h [code]
     
    file  distances.h [code]
     
    file  export.h [code]
     
    file  gl.h [code]
     
    file  glibc-sched.h [code]
     
    file  helper.h [code]
     
    file  levelzero.h [code]
     
    file  linux-libnuma.h [code]
     
    file  linux.h [code]
     
    file  memattrs.h [code]
     
    file  nvml.h [code]
     
    file  opencl.h [code]
     
    file  openfabrics-verbs.h [code]
     
    file  plugins.h [code]
     
    file  rsmi.h [code]
     
    file  shmem.h [code]
     
    file  windows.h [code]
     
    -
    - - - - - - - - -
    -
    -
    include Directory Reference
    -
    -
    - - - - -

    -Directories

    directory  hwloc
     
    - - - - - -

    -Files

    file  hwloc.h [code]
     
    file  netloc.h [code]
     
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/projects/hwloc/doc/v2.9.1/dudley.png b/projects/hwloc/doc/v2.9.1/dudley.png deleted file mode 100644 index a1df53f98..000000000 Binary files a/projects/hwloc/doc/v2.9.1/dudley.png and /dev/null differ diff --git a/projects/hwloc/doc/v2.9.1/dynsections.js b/projects/hwloc/doc/v2.9.1/dynsections.js deleted file mode 100644 index 3174bd7be..000000000 --- a/projects/hwloc/doc/v2.9.1/dynsections.js +++ /dev/null @@ -1,121 +0,0 @@ -/* - @licstart The following is the entire license notice for the JavaScript code in this file. - - The MIT License (MIT) - - Copyright (C) 1997-2020 by Dimitri van Heesch - - Permission is hereby granted, free of charge, to any person obtaining a copy of this software - and associated documentation files (the "Software"), to deal in the Software without restriction, - including without limitation the rights to use, copy, modify, merge, publish, distribute, - sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is - furnished to do so, subject to the following conditions: - - The above copyright notice and this permission notice shall be included in all copies or - substantial portions of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING - BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND - NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, - DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - - @licend The above is the entire license notice for the JavaScript code in this file - */ -function toggleVisibility(linkObj) -{ - var base = $(linkObj).attr('id'); - var summary = $('#'+base+'-summary'); - var content = $('#'+base+'-content'); - var trigger = $('#'+base+'-trigger'); - var src=$(trigger).attr('src'); - if (content.is(':visible')===true) { - content.hide(); - summary.show(); - $(linkObj).addClass('closed').removeClass('opened'); - $(trigger).attr('src',src.substring(0,src.length-8)+'closed.png'); - } else { - content.show(); - summary.hide(); - $(linkObj).removeClass('closed').addClass('opened'); - $(trigger).attr('src',src.substring(0,src.length-10)+'open.png'); - } - return false; -} - -function updateStripes() -{ - $('table.directory tr'). - removeClass('even').filter(':visible:even').addClass('even'); -} - -function toggleLevel(level) -{ - $('table.directory tr').each(function() { - var l = this.id.split('_').length-1; - var i = $('#img'+this.id.substring(3)); - var a = $('#arr'+this.id.substring(3)); - if (l - - - - - - -
    -
    Here is a list of all struct and union fields with links to the structures/unions they belong to:
    - -

    - a -

    - - -

    - b -

    - - -

    - c -

    - - -

    - d -

    - - -

    - e -

    - - -

    - f -

    - - -

    - g -

    - - -

    - i -

    - - -

    - k -

    - - -

    - l -

    - - -

    - m -

    - - -

    - n -

    - - -

    - o -

    - - -

    - p -

    - - -

    - r -

    - - -

    - s -

    - - -

    - t -

    - - -

    - u -

    - - -

    - v -

    -
    - - - - - - - -
    -  - -

    - a -

    - - -

    - b -

    - - -

    - c -

    - - -

    - d -

    - - -

    - e -

    - - -

    - f -

    - - -

    - g -

    - - -

    - i -

    - - -

    - k -

    - - -

    - l -

    - - -

    - m -

    - - -

    - n -

    - - -

    - o -

    - - -

    - p -

    - - -

    - r -

    - - -

    - s -

    - - -

    - t -

    - - -

    - u -

    - - -

    - v -

    -
    - - - - - - - -
    -
    -
    Hardware Locality
    -
    -
    -

    Portable abstraction of parallel architectures for high-performance computing

    -
    -

    -

    -

    -

    -Introduction

    -

    The Hardware Locality (hwloc) software project aims at easing the process of discovering hardware resources in parallel architectures. It offers command-line tools and a C API for consulting these resources, their locality, attributes, and interconnection. hwloc primarily aims at helping high-performance computing (HPC) applications, but is also applicable to any project seeking to exploit code and/or data locality on modern computing platforms.

    -

    hwloc is actually made of two subprojects distributed together:

    -

    -See also the Related pages tab above for links to other sections. -

    -

    Netloc may be disabled, but the original hwloc cannot. Both hwloc and netloc APIs are documented after these sections.

    -

    -

    -

    -

    -Installation

    -

    hwloc (https://www.open-mpi.org/projects/hwloc/) is available under the BSD license. It is hosted as a sub-project of the overall Open MPI project (https://www.open-mpi.org/). Note that hwloc does not require any functionality from Open MPI – it is a wholly separate (and much smaller!) project and code base. It just happens to be hosted as part of the overall Open MPI project.

    -

    -Basic Installation

    -

    Installation is the fairly common GNU-based process:

    -
    shell$ ./configure --prefix=...
-shell$ make
-shell$ make install
-

    hwloc- and netloc-specific configure options and requirements are documented in sections hwloc Installation and Netloc Installation respectively.

    -

    Also note that if you install supplemental libraries in non-standard locations, hwloc's configure script may not be able to find them without some help. You may need to specify additional CPPFLAGS, LDFLAGS, or PKG_CONFIG_PATH values on the configure command line.

    -

    For example, if libpciaccess was installed into /opt/pciaccess, hwloc's configure script may not find it be default. Try adding PKG_CONFIG_PATH to the ./configure command line, like this:

    -
    ./configure PKG_CONFIG_PATH=/opt/pciaccess/lib/pkgconfig ...
-

    Running the "lstopo" tool is a good way to check as a graphical output whether hwloc properly detected the architecture of your node. Netloc command-line tools can be used to display the network topology interconnecting your nodes.

    -

    -Installing from a Git clone

    -

    Additionally, the code can be directly cloned from Git:

    -
    shell$ git clone https://github.com/open-mpi/hwloc.git
-shell$ cd hwloc
-shell$ ./autogen.sh
-

    Note that GNU Autoconf >=2.63, Automake >=1.11 and Libtool >=2.2.6 are required when building from a Git clone.

    -

    Nightly development snapshots are available on the web site, they can be configured and built without any need for Git or GNU Autotools.

    -

    -

    -

    -

    -Questions and Bugs

    -

    Bugs should be reported in the tracker (https://github.com/open-mpi/hwloc/issues). Opening a new issue automatically displays lots of hints about how to debug and report issues.

    -

    Questions may be sent to the users or developers mailing lists (https://www.open-mpi.org/community/lists/hwloc.php).

    -

    There is also a #hwloc IRC channel on Libera Chat (irc.libera.chat).

    -
    -
    -'; - for (var i in data.children) { - result+='
  • '+ - data.children[i].text+''+ - makeTree(data.children[i],relPath)+'
    • '; - } - result+=''; - } - return result; - } - - $('#main-nav').append(makeTree(menudata,relPath)); - $('#main-nav').children(':first').addClass('sm sm-dox').attr('id','main-menu'); - if (searchEnabled) { - if (serverSide) { - $('#main-menu').append('
    • '); - } else { - $('#main-menu').append('
    • '); - } - } - $('#main-menu').smartmenus(); -} -/* @license-end */ diff --git a/projects/hwloc/doc/v2.9.1/menudata.js b/projects/hwloc/doc/v2.9.1/menudata.js deleted file mode 100644 index 7dc9262eb..000000000 --- a/projects/hwloc/doc/v2.9.1/menudata.js +++ /dev/null @@ -1,71 +0,0 @@ -/* - @licstart The following is the entire license notice for the JavaScript code in this file. - - The MIT License (MIT) - - Copyright (C) 1997-2020 by Dimitri van Heesch - - Permission is hereby granted, free of charge, to any person obtaining a copy of this software - and associated documentation files (the "Software"), to deal in the Software without restriction, - including without limitation the rights to use, copy, modify, merge, publish, distribute, - sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is - furnished to do so, subject to the following conditions: - - The above copyright notice and this permission notice shall be included in all copies or - substantial portions of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING - BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND - NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, - DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - - @licend The above is the entire license notice for the JavaScript code in this file -*/ -var menudata={children:[ -{text:"Main Page",url:"index.php"}, -{text:"Related Pages",url:"pages.php"}, -{text:"Modules",url:"modules.php"}, -{text:"Data Structures",url:"annotated.php",children:[ -{text:"Data Structures",url:"annotated.php"}, -{text:"Data Fields",url:"functions.php",children:[ -{text:"All",url:"functions.php",children:[ -{text:"a",url:"functions.php#index_a"}, -{text:"b",url:"functions.php#index_b"}, -{text:"c",url:"functions.php#index_c"}, -{text:"d",url:"functions.php#index_d"}, -{text:"e",url:"functions.php#index_e"}, -{text:"f",url:"functions.php#index_f"}, -{text:"g",url:"functions.php#index_g"}, -{text:"i",url:"functions.php#index_i"}, -{text:"k",url:"functions.php#index_k"}, -{text:"l",url:"functions.php#index_l"}, -{text:"m",url:"functions.php#index_m"}, -{text:"n",url:"functions.php#index_n"}, -{text:"o",url:"functions.php#index_o"}, -{text:"p",url:"functions.php#index_p"}, -{text:"r",url:"functions.php#index_r"}, -{text:"s",url:"functions.php#index_s"}, -{text:"t",url:"functions.php#index_t"}, -{text:"u",url:"functions.php#index_u"}, -{text:"v",url:"functions.php#index_v"}]}, -{text:"Variables",url:"functions_vars.php",children:[ -{text:"a",url:"functions_vars.php#index_a"}, -{text:"b",url:"functions_vars.php#index_b"}, -{text:"c",url:"functions_vars.php#index_c"}, -{text:"d",url:"functions_vars.php#index_d"}, -{text:"e",url:"functions_vars.php#index_e"}, -{text:"f",url:"functions_vars.php#index_f"}, -{text:"g",url:"functions_vars.php#index_g"}, -{text:"i",url:"functions_vars.php#index_i"}, -{text:"k",url:"functions_vars.php#index_k"}, -{text:"l",url:"functions_vars.php#index_l"}, -{text:"m",url:"functions_vars.php#index_m"}, -{text:"n",url:"functions_vars.php#index_n"}, -{text:"o",url:"functions_vars.php#index_o"}, -{text:"p",url:"functions_vars.php#index_p"}, -{text:"r",url:"functions_vars.php#index_r"}, -{text:"s",url:"functions_vars.php#index_s"}, -{text:"t",url:"functions_vars.php#index_t"}, -{text:"u",url:"functions_vars.php#index_u"}, -{text:"v",url:"functions_vars.php#index_v"}]}]}]}]} diff --git a/projects/hwloc/doc/v2.9.1/modules.php b/projects/hwloc/doc/v2.9.1/modules.php deleted file mode 100644 index 89f3951f8..000000000 --- a/projects/hwloc/doc/v2.9.1/modules.php +++ /dev/null @@ -1,92 +0,0 @@ - - - - - - -
    -
    -
    -
    Modules
    -
    -
    -
    Here is a list of all modules:
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     API version
     Object Sets (hwloc_cpuset_t and hwloc_nodeset_t)
     Object Types
     Object Structure and Attributes
     Topology Creation and Destruction
     Object levels, depths and types
     Converting between Object Types and Attributes, and Strings
     Consulting and Adding Key-Value Info Attributes
     CPU binding
     Memory binding
     Changing the Source of Topology Discovery
     Topology Detection Configuration and Query
     Modifying a loaded Topology
     Finding Objects inside a CPU set
     Finding Objects covering at least CPU set
     Looking at Ancestor and Child Objects
     Kinds of object Type
     Looking at Cache Objects
     Finding objects, miscellaneous helpers
     Distributing items over a topology
     CPU and node sets of entire topologies
     Converting between CPU sets and node sets
     Finding I/O objects
     The bitmap API
     Exporting Topologies to XML
     Exporting Topologies to Synthetic
     Retrieve distances between objects
     Helpers for consulting distance matrices
     Add distances between objects
     Remove distances between objects
     Comparing memory node attributes for finding where to allocate on
     Managing memory attributes
     Kinds of CPU cores
     Linux-specific helpers
     Interoperability with Linux libnuma unsigned long masks
     Interoperability with Linux libnuma bitmask
     Windows-specific helpers
     Interoperability with glibc sched affinity
     Interoperability with OpenCL
     Interoperability with the CUDA Driver API
     Interoperability with the CUDA Runtime API
     Interoperability with the NVIDIA Management Library
     Interoperability with the ROCm SMI Management Library
     Interoperability with the oneAPI Level Zero interface.
     Interoperability with OpenGL displays
     Interoperability with OpenFabrics
     Topology differences
     Sharing topologies between processes
     Components and Plugins: Discovery components
     Components and Plugins: Discovery backends
     Components and Plugins: Generic components
     Components and Plugins: Core functions to be used by components
     Components and Plugins: Filtering objects
     Components and Plugins: helpers for PCI discovery
     Components and Plugins: finding PCI objects during other discoveries
     Netloc API
    -
    -
    - - - - - - - -
    -
    -
    Related Pages
    -
    -
    -
    Here is a list of all related documentation pages:
    - - - - - - - - - - - - - - - - - - - - -
     Hardware Locality (hwloc) Introduction
     Terms and Definitions
     Command-Line Tools
     Environment Variables
     CPU and Memory Binding Overview
     I/O Devices
     Miscellaneous objects
     Object attributes
     Topology Attributes: Distances, Memory Attributes and CPU Kinds
     Importing and exporting topologies from/to XML files
     Synthetic topologies
     Interoperability With Other Software
     Thread Safety
     Components and plugins
     Embedding hwloc in Other Software
     Frequently Asked Questions (FAQ)
     Upgrading to the hwloc 2.0 API
     Network Locality (netloc)
     Netloc with Scotch
    -
    -
    -li>h1,.sm>li>h2,.sm>li>h3,.sm>li>h4,.sm>li>h5,.sm>li>h6{margin:0;padding:0}.sm ul{display:none}.sm li,.sm a{position:relative}.sm a{display:block}.sm a.disabled{cursor:not-allowed}.sm:after{content:"\00a0";display:block;height:0;font:0px/0 serif;clear:both;visibility:hidden;overflow:hidden}.sm,.sm *,.sm *:before,.sm *:after{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box}.sm-dox{background-image:url("tab_b.png")}.sm-dox a,.sm-dox a:focus,.sm-dox a:hover,.sm-dox a:active{padding:0px 12px;padding-right:43px;font-family:"Lucida Grande","Geneva","Helvetica",Arial,sans-serif;font-size:13px;font-weight:bold;line-height:36px;text-decoration:none;text-shadow:0px 1px 1px rgba(255,255,255,0.9);color:#283A5D;outline:none}.sm-dox a:hover{background-image:url("tab_a.png");background-repeat:repeat-x;color:#fff;text-shadow:0px 1px 1px #000}.sm-dox a.current{color:#D23600}.sm-dox a.disabled{color:#bbb}.sm-dox a span.sub-arrow{position:absolute;top:50%;margin-top:-14px;left:auto;right:3px;width:28px;height:28px;overflow:hidden;font:bold 12px/28px monospace !important;text-align:center;text-shadow:none;background:rgba(255,255,255,0.5);border-radius:5px}.sm-dox a.highlighted span.sub-arrow:before{display:block;content:'-'}.sm-dox>li:first-child>a,.sm-dox>li:first-child>:not(ul) a{border-radius:5px 5px 0 0}.sm-dox>li:last-child>a,.sm-dox>li:last-child>*:not(ul) a,.sm-dox>li:last-child>ul,.sm-dox>li:last-child>ul>li:last-child>a,.sm-dox>li:last-child>ul>li:last-child>*:not(ul) a,.sm-dox>li:last-child>ul>li:last-child>ul,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>a,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>*:not(ul) a,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>a,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>*:not(ul) a,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>ul,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>a,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>*:not(ul) a,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>ul{border-radius:0 0 5px 5px}.sm-dox>li:last-child>a.highlighted,.sm-dox>li:last-child>*:not(ul) a.highlighted,.sm-dox>li:last-child>ul>li:last-child>a.highlighted,.sm-dox>li:last-child>ul>li:last-child>*:not(ul) a.highlighted,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>a.highlighted,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>*:not(ul) a.highlighted,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>a.highlighted,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>*:not(ul) a.highlighted,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>a.highlighted,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>*:not(ul) a.highlighted{border-radius:0}.sm-dox ul{background:rgba(162,162,162,0.1)}.sm-dox ul a,.sm-dox ul a:focus,.sm-dox ul a:hover,.sm-dox ul a:active{font-size:12px;border-left:8px solid transparent;line-height:36px;text-shadow:none;background-color:white;background-image:none}.sm-dox ul a:hover{background-image:url("tab_a.png");background-repeat:repeat-x;color:#fff;text-shadow:0px 1px 1px #000}.sm-dox ul ul a,.sm-dox ul ul a:hover,.sm-dox ul ul a:focus,.sm-dox ul ul a:active{border-left:16px solid transparent}.sm-dox ul ul ul a,.sm-dox ul ul ul a:hover,.sm-dox ul ul ul a:focus,.sm-dox ul ul ul a:active{border-left:24px solid transparent}.sm-dox ul ul ul ul a,.sm-dox ul ul ul ul a:hover,.sm-dox ul ul ul ul a:focus,.sm-dox ul ul ul ul a:active{border-left:32px solid transparent}.sm-dox ul ul ul ul ul a,.sm-dox ul ul ul ul ul a:hover,.sm-dox ul ul ul ul ul a:focus,.sm-dox ul ul ul ul ul a:active{border-left:40px solid transparent}@media (min-width: 768px){.sm-dox ul{position:absolute;width:12em}.sm-dox li{float:left}.sm-dox.sm-rtl li{float:right}.sm-dox ul li,.sm-dox.sm-rtl ul li,.sm-dox.sm-vertical li{float:none}.sm-dox a{white-space:nowrap}.sm-dox ul a,.sm-dox.sm-vertical a{white-space:normal}.sm-dox .sm-nowrap>li>a,.sm-dox .sm-nowrap>li>:not(ul) a{white-space:nowrap}.sm-dox{padding:0 10px;background-image:url("tab_b.png");line-height:36px}.sm-dox a span.sub-arrow{top:50%;margin-top:-2px;right:12px;width:0;height:0;border-width:4px;border-style:solid dashed dashed dashed;border-color:#283A5D transparent transparent transparent;background:transparent;border-radius:0}.sm-dox a,.sm-dox a:focus,.sm-dox a:active,.sm-dox a:hover,.sm-dox a.highlighted{padding:0px 12px;background-image:url("tab_s.png");background-repeat:no-repeat;background-position:right;border-radius:0 !important}.sm-dox a:hover{background-image:url("tab_a.png");background-repeat:repeat-x;color:#fff;text-shadow:0px 1px 1px #000}.sm-dox a:hover span.sub-arrow{border-color:#fff transparent transparent transparent}.sm-dox a.has-submenu{padding-right:24px}.sm-dox li{border-top:0}.sm-dox>li>ul:before,.sm-dox>li>ul:after{content:'';position:absolute;top:-18px;left:30px;width:0;height:0;overflow:hidden;border-width:9px;border-style:dashed dashed solid dashed;border-color:transparent transparent #bbb transparent}.sm-dox>li>ul:after{top:-16px;left:31px;border-width:8px;border-color:transparent transparent #fff transparent}.sm-dox ul{border:1px solid #bbb;padding:5px 0;background:#fff;border-radius:5px !important;box-shadow:0 5px 9px rgba(0,0,0,0.2)}.sm-dox ul a span.sub-arrow{right:8px;top:50%;margin-top:-5px;border-width:5px;border-color:transparent transparent transparent #555;border-style:dashed dashed dashed solid}.sm-dox ul a,.sm-dox ul a:hover,.sm-dox ul a:focus,.sm-dox ul a:active,.sm-dox ul a.highlighted{color:#555;background-image:none;border:0 !important;color:#555;background-image:none}.sm-dox ul a:hover{background-image:url("tab_a.png");background-repeat:repeat-x;color:#fff;text-shadow:0px 1px 1px #000}.sm-dox ul a:hover span.sub-arrow{border-color:transparent transparent transparent #fff}.sm-dox span.scroll-up,.sm-dox span.scroll-down{position:absolute;display:none;visibility:hidden;overflow:hidden;background:#fff;height:36px}.sm-dox span.scroll-up:hover,.sm-dox span.scroll-down:hover{background:#eee}.sm-dox span.scroll-up:hover span.scroll-up-arrow,.sm-dox span.scroll-up:hover span.scroll-down-arrow{border-color:transparent transparent #D23600 transparent}.sm-dox span.scroll-down:hover span.scroll-down-arrow{border-color:#D23600 transparent transparent transparent}.sm-dox span.scroll-up-arrow,.sm-dox span.scroll-down-arrow{position:absolute;top:0;left:50%;margin-left:-6px;width:0;height:0;overflow:hidden;border-width:6px;border-style:dashed dashed solid dashed;border-color:transparent transparent #555 transparent}.sm-dox span.scroll-down-arrow{top:8px;border-style:solid dashed dashed dashed;border-color:#555 transparent transparent transparent}.sm-dox.sm-rtl a.has-submenu{padding-right:12px;padding-left:24px}.sm-dox.sm-rtl a span.sub-arrow{right:auto;left:12px}.sm-dox.sm-rtl.sm-vertical a.has-submenu{padding:10px 20px}.sm-dox.sm-rtl.sm-vertical a span.sub-arrow{right:auto;left:8px;border-style:dashed solid dashed dashed;border-color:transparent #555 transparent transparent}.sm-dox.sm-rtl>li>ul:before{left:auto;right:30px}.sm-dox.sm-rtl>li>ul:after{left:auto;right:31px}.sm-dox.sm-rtl ul a.has-submenu{padding:10px 20px !important}.sm-dox.sm-rtl ul a span.sub-arrow{right:auto;left:8px;border-style:dashed solid dashed dashed;border-color:transparent #555 transparent transparent}.sm-dox.sm-vertical{padding:10px 0;border-radius:5px}.sm-dox.sm-vertical a{padding:10px 20px}.sm-dox.sm-vertical a:hover,.sm-dox.sm-vertical a:focus,.sm-dox.sm-vertical a:active,.sm-dox.sm-vertical a.highlighted{background:#fff}.sm-dox.sm-vertical a.disabled{background-image:url("tab_b.png")}.sm-dox.sm-vertical a span.sub-arrow{right:8px;top:50%;margin-top:-5px;border-width:5px;border-style:dashed dashed dashed solid;border-color:transparent transparent transparent #555}.sm-dox.sm-vertical>li>ul:before,.sm-dox.sm-vertical>li>ul:after{display:none}.sm-dox.sm-vertical ul a{padding:10px 20px}.sm-dox.sm-vertical ul a:hover,.sm-dox.sm-vertical ul a:focus,.sm-dox.sm-vertical ul a:active,.sm-dox.sm-vertical ul a.highlighted{background:#eee}.sm-dox.sm-vertical ul a.disabled{background:#fff}} diff --git a/projects/hwloc/doc/v2.9.1/www.open-mpi.org-css.inc b/projects/hwloc/doc/v2.9.1/www.open-mpi.org-css.inc deleted file mode 100644 index 339ffeb0b..000000000 --- a/projects/hwloc/doc/v2.9.1/www.open-mpi.org-css.inc +++ /dev/null @@ -1,2 +0,0 @@ - - diff --git a/projects/hwloc/doc/v2.9.1/www.open-mpi.org-footer.inc b/projects/hwloc/doc/v2.9.1/www.open-mpi.org-footer.inc deleted file mode 100644 index 50e092203..000000000 --- a/projects/hwloc/doc/v2.9.1/www.open-mpi.org-footer.inc +++ /dev/null @@ -1,2 +0,0 @@ - diff --git a/projects/hwloc/doc/v2.9.2/a00089_source.php b/projects/hwloc/doc/v2.9.2/a00089_source.php deleted file mode 100644 index 160f10af0..000000000 --- a/projects/hwloc/doc/v2.9.2/a00089_source.php +++ /dev/null @@ -1,927 +0,0 @@ - - - - - - - - -
    -
    hwloc.h
    -
    -
    -
    1/*
    -
    2 * Copyright © 2009 CNRS
    -
    3 * Copyright © 2009-2022 Inria. All rights reserved.
    -
    4 * Copyright © 2009-2012 Université Bordeaux
    -
    5 * Copyright © 2009-2020 Cisco Systems, Inc. All rights reserved.
    -
    6 * See COPYING in top-level directory.
    -
    7 */
    -
    8
    -
    9/*=====================================================================
    -
    10 * PLEASE GO READ THE DOCUMENTATION!
    -
    11 * ------------------------------------------------
    -
    12 * $tarball_directory/doc/doxygen-doc/
    -
    13 * or
    -
    14 * https://www.open-mpi.org/projects/hwloc/doc/
    -
    15 *=====================================================================
    -
    16 *
    -
    17 * FAIR WARNING: Do NOT expect to be able to figure out all the
    -
    18 * subtleties of hwloc by simply reading function prototypes and
    -
    19 * constant descrptions here in this file.
    -
    20 *
    -
    21 * Hwloc has wonderful documentation in both PDF and HTML formats for
    -
    22 * your reading pleasure. The formal documentation explains a LOT of
    -
    23 * hwloc-specific concepts, provides definitions, and discusses the
    -
    24 * "big picture" for many of the things that you'll find here in this
    -
    25 * header file.
    -
    26 *
    -
    27 * The PDF/HTML documentation was generated via Doxygen; much of what
    -
    28 * you'll see in there is also here in this file. BUT THERE IS A LOT
    -
    29 * THAT IS IN THE PDF/HTML THAT IS ***NOT*** IN hwloc.h!
    -
    30 *
    -
    31 * There are entire paragraph-length descriptions, discussions, and
    -
    32 * pretty pictures to explain subtle corner cases, provide concrete
    -
    33 * examples, etc.
    -
    34 *
    -
    35 * Please, go read the documentation. :-)
    -
    36 *
    -
    37 * Moreover there are several examples of hwloc use under doc/examples
    -
    38 * in the source tree.
    -
    39 *
    -
    40 *=====================================================================*/
    -
    41
    -
    53#ifndef HWLOC_H
    -
    54#define HWLOC_H
    -
    55
    -
    56#include "hwloc/autogen/config.h"
    -
    57
    -
    58#include <sys/types.h>
    -
    59#include <stdio.h>
    -
    60#include <string.h>
    -
    61#include <limits.h>
    -
    62
    -
    63/*
    -
    64 * Symbol transforms
    -
    65 */
    -
    66#include "hwloc/rename.h"
    -
    67
    -
    68/*
    -
    69 * Bitmap definitions
    -
    70 */
    -
    71
    -
    72#include "hwloc/bitmap.h"
    -
    73
    -
    74
    -
    75#ifdef __cplusplus
    -
    76extern "C" {
    -
    77#endif
    -
    78
    -
    79
    -
    115#define HWLOC_API_VERSION 0x00020800
    -
    116
    -
    123HWLOC_DECLSPEC unsigned hwloc_get_api_version(void);
    -
    124
    -
    126#define HWLOC_COMPONENT_ABI 7
    -
    127
    -
    161typedef hwloc_bitmap_t hwloc_cpuset_t;
    -
    163typedef hwloc_const_bitmap_t hwloc_const_cpuset_t;
    -
    164
    -
    178typedef hwloc_bitmap_t hwloc_nodeset_t;
    -
    181typedef hwloc_const_bitmap_t hwloc_const_nodeset_t;
    -
    182
    -
    197typedef enum {
    -
    198
    -
    200#define HWLOC_OBJ_TYPE_MIN HWLOC_OBJ_MACHINE /* Sentinel value */
    -
    203 HWLOC_OBJ_MACHINE,
    -
    212 HWLOC_OBJ_PACKAGE,
    -
    218 HWLOC_OBJ_CORE,
    -
    222 HWLOC_OBJ_PU,
    -
    234 HWLOC_OBJ_L1CACHE,
    -
    235 HWLOC_OBJ_L2CACHE,
    -
    236 HWLOC_OBJ_L3CACHE,
    -
    237 HWLOC_OBJ_L4CACHE,
    -
    238 HWLOC_OBJ_L5CACHE,
    -
    240 HWLOC_OBJ_L1ICACHE,
    -
    241 HWLOC_OBJ_L2ICACHE,
    -
    242 HWLOC_OBJ_L3ICACHE,
    -
    244 HWLOC_OBJ_GROUP,
    -
    257 HWLOC_OBJ_NUMANODE,
    -
    278 HWLOC_OBJ_BRIDGE,
    -
    290 HWLOC_OBJ_PCI_DEVICE,
    -
    300 HWLOC_OBJ_OS_DEVICE,
    -
    311 HWLOC_OBJ_MISC,
    -
    326 HWLOC_OBJ_MEMCACHE,
    -
    339 HWLOC_OBJ_DIE,
    -
    343 HWLOC_OBJ_TYPE_MAX
    -
    344} hwloc_obj_type_t;
    -
    345
    -
    347typedef enum hwloc_obj_cache_type_e {
    -
    348 HWLOC_OBJ_CACHE_UNIFIED,
    -
    349 HWLOC_OBJ_CACHE_DATA,
    -
    350 HWLOC_OBJ_CACHE_INSTRUCTION
    -
    351} hwloc_obj_cache_type_t;
    -
    352
    -
    354typedef enum hwloc_obj_bridge_type_e {
    -
    355 HWLOC_OBJ_BRIDGE_HOST,
    -
    356 HWLOC_OBJ_BRIDGE_PCI
    -
    357} hwloc_obj_bridge_type_t;
    -
    358
    -
    360typedef enum hwloc_obj_osdev_type_e {
    -
    361 HWLOC_OBJ_OSDEV_BLOCK,
    -
    363 HWLOC_OBJ_OSDEV_GPU,
    -
    366 HWLOC_OBJ_OSDEV_NETWORK,
    -
    368 HWLOC_OBJ_OSDEV_OPENFABRICS,
    -
    372 HWLOC_OBJ_OSDEV_DMA,
    -
    374 HWLOC_OBJ_OSDEV_COPROC
    -
    377} hwloc_obj_osdev_type_t;
    -
    378
    -
    401HWLOC_DECLSPEC int hwloc_compare_types (hwloc_obj_type_t type1, hwloc_obj_type_t type2) __hwloc_attribute_const;
    -
    402
    -
    404#define HWLOC_TYPE_UNORDERED INT_MAX
    -
    405
    -
    414union hwloc_obj_attr_u;
    -
    415
    -
    420struct hwloc_obj {
    -
    421 /* physical information */
    -
    422 hwloc_obj_type_t type;
    -
    423 char *subtype;
    -
    425 unsigned os_index;
    -
    430#define HWLOC_UNKNOWN_INDEX (unsigned)-1
    -
    431
    -
    432 char *name;
    -
    437 hwloc_uint64_t total_memory;
    -
    439 union hwloc_obj_attr_u *attr;
    -
    442 /* global position */
    -
    443 int depth;
    -
    458 unsigned logical_index;
    -
    465 /* cousins are all objects of the same type (and depth) across the entire topology */
    -
    466 struct hwloc_obj *next_cousin;
    -
    467 struct hwloc_obj *prev_cousin;
    -
    469 /* children of the same parent are siblings, even if they may have different type and depth */
    -
    470 struct hwloc_obj *parent;
    -
    471 unsigned sibling_rank;
    -
    472 struct hwloc_obj *next_sibling;
    -
    473 struct hwloc_obj *prev_sibling;
    -
    476 unsigned arity;
    -
    480 struct hwloc_obj **children;
    -
    481 struct hwloc_obj *first_child;
    -
    482 struct hwloc_obj *last_child;
    -
    485 int symmetric_subtree;
    -
    496 unsigned memory_arity;
    -
    499 struct hwloc_obj *memory_first_child;
    -
    514 unsigned io_arity;
    -
    517 struct hwloc_obj *io_first_child;
    -
    526 unsigned misc_arity;
    -
    529 struct hwloc_obj *misc_first_child;
    -
    535 /* cpusets and nodesets */
    -
    536 hwloc_cpuset_t cpuset;
    -
    551 hwloc_cpuset_t complete_cpuset;
    -
    564 hwloc_nodeset_t nodeset;
    -
    586 hwloc_nodeset_t complete_nodeset;
    -
    602 struct hwloc_info_s *infos;
    -
    603 unsigned infos_count;
    -
    605 /* misc */
    -
    606 void *userdata;
    -
    611 hwloc_uint64_t gp_index;
    -
    616};
    -
    620typedef struct hwloc_obj * hwloc_obj_t;
    -
    621
    -
    623union hwloc_obj_attr_u {
    -
    625 struct hwloc_numanode_attr_s {
    -
    626 hwloc_uint64_t local_memory;
    -
    627 unsigned page_types_len;
    -
    633 struct hwloc_memory_page_type_s {
    -
    634 hwloc_uint64_t size;
    -
    635 hwloc_uint64_t count;
    -
    636 } * page_types;
    -
    637 } numanode;
    -
    638
    -
    640 struct hwloc_cache_attr_s {
    -
    641 hwloc_uint64_t size;
    -
    642 unsigned depth;
    -
    643 unsigned linesize;
    -
    644 int associativity;
    -
    646 hwloc_obj_cache_type_t type;
    -
    647 } cache;
    -
    649 struct hwloc_group_attr_s {
    -
    650 unsigned depth;
    -
    652 unsigned kind;
    -
    653 unsigned subkind;
    -
    654 unsigned char dont_merge;
    -
    655 } group;
    -
    657 struct hwloc_pcidev_attr_s {
    -
    658#ifndef HWLOC_HAVE_32BITS_PCI_DOMAIN
    -
    659 unsigned short domain; /* Only 16bits PCI domains are supported by default */
    -
    660#else
    -
    661 unsigned int domain; /* 32bits PCI domain support break the library ABI, hence it's disabled by default */
    -
    662#endif
    -
    663 unsigned char bus, dev, func;
    -
    664 unsigned short class_id;
    -
    665 unsigned short vendor_id, device_id, subvendor_id, subdevice_id;
    -
    666 unsigned char revision;
    -
    667 float linkspeed; /* in GB/s */
    -
    668 } pcidev;
    -
    670 struct hwloc_bridge_attr_s {
    -
    671 union {
    -
    672 struct hwloc_pcidev_attr_s pci;
    -
    673 } upstream;
    -
    674 hwloc_obj_bridge_type_t upstream_type;
    -
    675 union {
    -
    676 struct {
    -
    677#ifndef HWLOC_HAVE_32BITS_PCI_DOMAIN
    -
    678 unsigned short domain; /* Only 16bits PCI domains are supported by default */
    -
    679#else
    -
    680 unsigned int domain; /* 32bits PCI domain support break the library ABI, hence it's disabled by default */
    -
    681#endif
    -
    682 unsigned char secondary_bus, subordinate_bus;
    -
    683 } pci;
    -
    684 } downstream;
    -
    685 hwloc_obj_bridge_type_t downstream_type;
    -
    686 unsigned depth;
    -
    687 } bridge;
    -
    689 struct hwloc_osdev_attr_s {
    -
    690 hwloc_obj_osdev_type_t type;
    -
    691 } osdev;
    -
    692};
    -
    693
    -
    698struct hwloc_info_s {
    -
    699 char *name;
    -
    700 char *value;
    -
    701};
    -
    702
    -
    711struct hwloc_topology;
    -
    716typedef struct hwloc_topology * hwloc_topology_t;
    -
    717
    -
    724HWLOC_DECLSPEC int hwloc_topology_init (hwloc_topology_t *topologyp);
    -
    725
    -
    746HWLOC_DECLSPEC int hwloc_topology_load(hwloc_topology_t topology);
    -
    747
    -
    752HWLOC_DECLSPEC void hwloc_topology_destroy (hwloc_topology_t topology);
    -
    753
    -
    766HWLOC_DECLSPEC int hwloc_topology_dup(hwloc_topology_t *newtopology, hwloc_topology_t oldtopology);
    -
    767
    -
    785HWLOC_DECLSPEC int hwloc_topology_abi_check(hwloc_topology_t topology);
    -
    786
    -
    798HWLOC_DECLSPEC void hwloc_topology_check(hwloc_topology_t topology);
    -
    799
    -
    822HWLOC_DECLSPEC int hwloc_topology_get_depth(hwloc_topology_t __hwloc_restrict topology) __hwloc_attribute_pure;
    -
    823
    -
    850HWLOC_DECLSPEC int hwloc_get_type_depth (hwloc_topology_t topology, hwloc_obj_type_t type);
    -
    851
    -
    852enum hwloc_get_type_depth_e {
    -
    853 HWLOC_TYPE_DEPTH_UNKNOWN = -1,
    -
    854 HWLOC_TYPE_DEPTH_MULTIPLE = -2,
    -
    855 HWLOC_TYPE_DEPTH_NUMANODE = -3,
    -
    856 HWLOC_TYPE_DEPTH_BRIDGE = -4,
    -
    857 HWLOC_TYPE_DEPTH_PCI_DEVICE = -5,
    -
    858 HWLOC_TYPE_DEPTH_OS_DEVICE = -6,
    -
    859 HWLOC_TYPE_DEPTH_MISC = -7,
    -
    860 HWLOC_TYPE_DEPTH_MEMCACHE = -8
    -
    861};
    -
    862
    -
    882HWLOC_DECLSPEC int hwloc_get_memory_parents_depth (hwloc_topology_t topology);
    -
    883
    -
    897static __hwloc_inline int
    -
    898hwloc_get_type_or_below_depth (hwloc_topology_t topology, hwloc_obj_type_t type) __hwloc_attribute_pure;
    -
    899
    -
    913static __hwloc_inline int
    -
    914hwloc_get_type_or_above_depth (hwloc_topology_t topology, hwloc_obj_type_t type) __hwloc_attribute_pure;
    -
    915
    -
    924HWLOC_DECLSPEC hwloc_obj_type_t hwloc_get_depth_type (hwloc_topology_t topology, int depth) __hwloc_attribute_pure;
    -
    925
    -
    931HWLOC_DECLSPEC unsigned hwloc_get_nbobjs_by_depth (hwloc_topology_t topology, int depth) __hwloc_attribute_pure;
    -
    932
    -
    939static __hwloc_inline int
    -
    940hwloc_get_nbobjs_by_type (hwloc_topology_t topology, hwloc_obj_type_t type) __hwloc_attribute_pure;
    -
    941
    -
    948static __hwloc_inline hwloc_obj_t
    -
    949hwloc_get_root_obj (hwloc_topology_t topology) __hwloc_attribute_pure;
    -
    950
    -
    956HWLOC_DECLSPEC hwloc_obj_t hwloc_get_obj_by_depth (hwloc_topology_t topology, int depth, unsigned idx) __hwloc_attribute_pure;
    -
    957
    -
    965static __hwloc_inline hwloc_obj_t
    -
    966hwloc_get_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx) __hwloc_attribute_pure;
    -
    967
    -
    974static __hwloc_inline hwloc_obj_t
    -
    975hwloc_get_next_obj_by_depth (hwloc_topology_t topology, int depth, hwloc_obj_t prev);
    -
    976
    -
    985static __hwloc_inline hwloc_obj_t
    -
    986hwloc_get_next_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type,
    -
    987 hwloc_obj_t prev);
    -
    988
    -
    1007HWLOC_DECLSPEC const char * hwloc_obj_type_string (hwloc_obj_type_t type) __hwloc_attribute_const;
    -
    1008
    -
    1026HWLOC_DECLSPEC int hwloc_obj_type_snprintf(char * __hwloc_restrict string, size_t size,
    -
    1027 hwloc_obj_t obj,
    -
    1028 int verbose);
    -
    1029
    -
    1041HWLOC_DECLSPEC int hwloc_obj_attr_snprintf(char * __hwloc_restrict string, size_t size,
    -
    1042 hwloc_obj_t obj, const char * __hwloc_restrict separator,
    -
    1043 int verbose);
    -
    1044
    -
    1068HWLOC_DECLSPEC int hwloc_type_sscanf(const char *string,
    -
    1069 hwloc_obj_type_t *typep,
    -
    1070 union hwloc_obj_attr_u *attrp, size_t attrsize);
    -
    1071
    -
    1093HWLOC_DECLSPEC int hwloc_type_sscanf_as_depth(const char *string,
    -
    1094 hwloc_obj_type_t *typep,
    -
    1095 hwloc_topology_t topology, int *depthp);
    -
    1096
    -
    1115static __hwloc_inline const char *
    -
    1116hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name) __hwloc_attribute_pure;
    -
    1117
    -
    1134HWLOC_DECLSPEC int hwloc_obj_add_info(hwloc_obj_t obj, const char *name, const char *value);
    -
    1135
    -
    1207typedef enum {
    -
    1210 HWLOC_CPUBIND_PROCESS = (1<<0),
    -
    1211
    -
    1214 HWLOC_CPUBIND_THREAD = (1<<1),
    -
    1215
    -
    1239 HWLOC_CPUBIND_STRICT = (1<<2),
    -
    1240
    -
    1256 HWLOC_CPUBIND_NOMEMBIND = (1<<3)
    -
    1257} hwloc_cpubind_flags_t;
    -
    1258
    -
    1265HWLOC_DECLSPEC int hwloc_set_cpubind(hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags);
    -
    1266
    -
    1275HWLOC_DECLSPEC int hwloc_get_cpubind(hwloc_topology_t topology, hwloc_cpuset_t set, int flags);
    -
    1276
    -
    1290HWLOC_DECLSPEC int hwloc_set_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_cpuset_t set, int flags);
    -
    1291
    -
    1309HWLOC_DECLSPEC int hwloc_get_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags);
    -
    1310
    -
    1311#ifdef hwloc_thread_t
    -
    1321HWLOC_DECLSPEC int hwloc_set_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_const_cpuset_t set, int flags);
    -
    1322#endif
    -
    1323
    -
    1324#ifdef hwloc_thread_t
    -
    1338HWLOC_DECLSPEC int hwloc_get_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_cpuset_t set, int flags);
    -
    1339#endif
    -
    1340
    -
    1360HWLOC_DECLSPEC int hwloc_get_last_cpu_location(hwloc_topology_t topology, hwloc_cpuset_t set, int flags);
    -
    1361
    -
    1384HWLOC_DECLSPEC int hwloc_get_proc_last_cpu_location(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags);
    -
    1385
    -
    1465typedef enum {
    -
    1473 HWLOC_MEMBIND_DEFAULT = 0,
    -
    1474
    -
    1484 HWLOC_MEMBIND_FIRSTTOUCH = 1,
    -
    1485
    -
    1488 HWLOC_MEMBIND_BIND = 2,
    -
    1489
    -
    1497 HWLOC_MEMBIND_INTERLEAVE = 3,
    -
    1498
    -
    1504 HWLOC_MEMBIND_NEXTTOUCH = 4,
    -
    1505
    -
    1512 HWLOC_MEMBIND_MIXED = -1
    -
    1513} hwloc_membind_policy_t;
    -
    1514
    -
    1528typedef enum {
    -
    1533 HWLOC_MEMBIND_PROCESS = (1<<0),
    -
    1534
    -
    1538 HWLOC_MEMBIND_THREAD = (1<<1),
    -
    1539
    -
    1546 HWLOC_MEMBIND_STRICT = (1<<2),
    -
    1547
    -
    1552 HWLOC_MEMBIND_MIGRATE = (1<<3),
    -
    1553
    -
    1565 HWLOC_MEMBIND_NOCPUBIND = (1<<4),
    -
    1566
    -
    1576 HWLOC_MEMBIND_BYNODESET = (1<<5)
    -
    1577} hwloc_membind_flags_t;
    -
    1578
    -
    1595HWLOC_DECLSPEC int hwloc_set_membind(hwloc_topology_t topology, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags);
    -
    1596
    -
    1646HWLOC_DECLSPEC int hwloc_get_membind(hwloc_topology_t topology, hwloc_bitmap_t set, hwloc_membind_policy_t * policy, int flags);
    -
    1647
    -
    1661HWLOC_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);
    -
    1662
    -
    1707HWLOC_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);
    -
    1708
    -
    1719HWLOC_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);
    -
    1720
    -
    1752HWLOC_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);
    -
    1753
    -
    1776HWLOC_DECLSPEC int hwloc_get_area_memlocation(hwloc_topology_t topology, const void *addr, size_t len, hwloc_bitmap_t set, int flags);
    -
    1777
    -
    1787HWLOC_DECLSPEC void *hwloc_alloc(hwloc_topology_t topology, size_t len);
    -
    1788
    -
    1804HWLOC_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;
    -
    1805
    -
    1820static __hwloc_inline void *
    -
    1821hwloc_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;
    -
    1822
    -
    1828HWLOC_DECLSPEC int hwloc_free(hwloc_topology_t topology, void *addr, size_t len);
    -
    1829
    -
    1871HWLOC_DECLSPEC int hwloc_topology_set_pid(hwloc_topology_t __hwloc_restrict topology, hwloc_pid_t pid);
    -
    1872
    -
    1904HWLOC_DECLSPEC int hwloc_topology_set_synthetic(hwloc_topology_t __hwloc_restrict topology, const char * __hwloc_restrict description);
    -
    1905
    -
    1933HWLOC_DECLSPEC int hwloc_topology_set_xml(hwloc_topology_t __hwloc_restrict topology, const char * __hwloc_restrict xmlpath);
    -
    1934
    -
    1962HWLOC_DECLSPEC int hwloc_topology_set_xmlbuffer(hwloc_topology_t __hwloc_restrict topology, const char * __hwloc_restrict buffer, int size);
    -
    1963
    -
    1966enum hwloc_topology_components_flag_e {
    -
    1970 HWLOC_TOPOLOGY_COMPONENTS_FLAG_BLACKLIST = (1UL<<0)
    -
    1971};
    -
    1972
    -
    1990HWLOC_DECLSPEC int hwloc_topology_set_components(hwloc_topology_t __hwloc_restrict topology, unsigned long flags, const char * __hwloc_restrict name);
    -
    1991
    -
    2010enum hwloc_topology_flags_e {
    -
    2032 HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED = (1UL<<0),
    -
    2033
    -
    2052 HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM = (1UL<<1),
    -
    2053
    -
    2073 HWLOC_TOPOLOGY_FLAG_THISSYSTEM_ALLOWED_RESOURCES = (1UL<<2),
    -
    2074
    -
    2097 HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT = (1UL<<3),
    -
    2098
    -
    2122 HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_CPUBINDING = (1UL<<4),
    -
    2123
    -
    2144 HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_MEMBINDING = (1UL<<5),
    -
    2145
    -
    2159 HWLOC_TOPOLOGY_FLAG_DONT_CHANGE_BINDING = (1UL<<6),
    -
    2160
    -
    2166 HWLOC_TOPOLOGY_FLAG_NO_DISTANCES = (1UL<<7),
    -
    2167
    -
    2172 HWLOC_TOPOLOGY_FLAG_NO_MEMATTRS = (1UL<<8),
    -
    2173
    -
    2178 HWLOC_TOPOLOGY_FLAG_NO_CPUKINDS = (1UL<<9)
    -
    2179};
    -
    2180
    -
    2195HWLOC_DECLSPEC int hwloc_topology_set_flags (hwloc_topology_t topology, unsigned long flags);
    -
    2196
    -
    2208HWLOC_DECLSPEC unsigned long hwloc_topology_get_flags (hwloc_topology_t topology);
    -
    2209
    -
    2219HWLOC_DECLSPEC int hwloc_topology_is_thissystem(hwloc_topology_t __hwloc_restrict topology) __hwloc_attribute_pure;
    -
    2220
    -
    2222struct hwloc_topology_discovery_support {
    -
    2224 unsigned char pu;
    -
    2226 unsigned char numa;
    -
    2228 unsigned char numa_memory;
    -
    2230 unsigned char disallowed_pu;
    -
    2232 unsigned char disallowed_numa;
    -
    2234 unsigned char cpukind_efficiency;
    -
    2235};
    -
    2236
    -
    2242struct hwloc_topology_cpubind_support {
    -
    2244 unsigned char set_thisproc_cpubind;
    -
    2246 unsigned char get_thisproc_cpubind;
    -
    2248 unsigned char set_proc_cpubind;
    -
    2250 unsigned char get_proc_cpubind;
    -
    2252 unsigned char set_thisthread_cpubind;
    -
    2254 unsigned char get_thisthread_cpubind;
    -
    2256 unsigned char set_thread_cpubind;
    -
    2258 unsigned char get_thread_cpubind;
    -
    2260 unsigned char get_thisproc_last_cpu_location;
    -
    2262 unsigned char get_proc_last_cpu_location;
    -
    2264 unsigned char get_thisthread_last_cpu_location;
    -
    2265};
    -
    2266
    -
    2272struct hwloc_topology_membind_support {
    -
    2274 unsigned char set_thisproc_membind;
    -
    2276 unsigned char get_thisproc_membind;
    -
    2278 unsigned char set_proc_membind;
    -
    2280 unsigned char get_proc_membind;
    -
    2282 unsigned char set_thisthread_membind;
    -
    2284 unsigned char get_thisthread_membind;
    -
    2286 unsigned char set_area_membind;
    -
    2288 unsigned char get_area_membind;
    -
    2290 unsigned char alloc_membind;
    -
    2292 unsigned char firsttouch_membind;
    -
    2294 unsigned char bind_membind;
    -
    2296 unsigned char interleave_membind;
    -
    2298 unsigned char nexttouch_membind;
    -
    2300 unsigned char migrate_membind;
    -
    2302 unsigned char get_area_memlocation;
    -
    2303};
    -
    2304
    -
    2307struct hwloc_topology_misc_support {
    -
    2309 unsigned char imported_support;
    -
    2310};
    -
    2311
    -
    2318struct hwloc_topology_support {
    -
    2319 struct hwloc_topology_discovery_support *discovery;
    -
    2320 struct hwloc_topology_cpubind_support *cpubind;
    -
    2321 struct hwloc_topology_membind_support *membind;
    -
    2322 struct hwloc_topology_misc_support *misc;
    -
    2323};
    -
    2324
    -
    2354HWLOC_DECLSPEC const struct hwloc_topology_support *hwloc_topology_get_support(hwloc_topology_t __hwloc_restrict topology);
    -
    2355
    -
    2365enum hwloc_type_filter_e {
    -
    2371 HWLOC_TYPE_FILTER_KEEP_ALL = 0,
    -
    2372
    -
    2379 HWLOC_TYPE_FILTER_KEEP_NONE = 1,
    -
    2380
    -
    2393 HWLOC_TYPE_FILTER_KEEP_STRUCTURE = 2,
    -
    2394
    -
    2408 HWLOC_TYPE_FILTER_KEEP_IMPORTANT = 3
    -
    2409};
    -
    2410
    -
    2415HWLOC_DECLSPEC int hwloc_topology_set_type_filter(hwloc_topology_t topology, hwloc_obj_type_t type, enum hwloc_type_filter_e filter);
    -
    2416
    -
    2421HWLOC_DECLSPEC int hwloc_topology_get_type_filter(hwloc_topology_t topology, hwloc_obj_type_t type, enum hwloc_type_filter_e *filter);
    -
    2422
    -
    2429HWLOC_DECLSPEC int hwloc_topology_set_all_types_filter(hwloc_topology_t topology, enum hwloc_type_filter_e filter);
    -
    2430
    -
    2437HWLOC_DECLSPEC int hwloc_topology_set_cache_types_filter(hwloc_topology_t topology, enum hwloc_type_filter_e filter);
    -
    2438
    -
    2445HWLOC_DECLSPEC int hwloc_topology_set_icache_types_filter(hwloc_topology_t topology, enum hwloc_type_filter_e filter);
    -
    2446
    -
    2451HWLOC_DECLSPEC int hwloc_topology_set_io_types_filter(hwloc_topology_t topology, enum hwloc_type_filter_e filter);
    -
    2452
    -
    2463HWLOC_DECLSPEC void hwloc_topology_set_userdata(hwloc_topology_t topology, const void *userdata);
    -
    2464
    -
    2473HWLOC_DECLSPEC void * hwloc_topology_get_userdata(hwloc_topology_t topology);
    -
    2474
    -
    2484enum hwloc_restrict_flags_e {
    -
    2490 HWLOC_RESTRICT_FLAG_REMOVE_CPULESS = (1UL<<0),
    -
    2491
    -
    2496 HWLOC_RESTRICT_FLAG_BYNODESET = (1UL<<3),
    -
    2497
    -
    2503 HWLOC_RESTRICT_FLAG_REMOVE_MEMLESS = (1UL<<4),
    -
    2504
    -
    2509 HWLOC_RESTRICT_FLAG_ADAPT_MISC = (1UL<<1),
    -
    2510
    -
    2515 HWLOC_RESTRICT_FLAG_ADAPT_IO = (1UL<<2)
    -
    2516};
    -
    2517
    -
    2542HWLOC_DECLSPEC int hwloc_topology_restrict(hwloc_topology_t __hwloc_restrict topology, hwloc_const_bitmap_t set, unsigned long flags);
    -
    2543
    -
    2545enum hwloc_allow_flags_e {
    -
    2550 HWLOC_ALLOW_FLAG_ALL = (1UL<<0),
    -
    2551
    -
    2559 HWLOC_ALLOW_FLAG_LOCAL_RESTRICTIONS = (1UL<<1),
    -
    2560
    -
    2563 HWLOC_ALLOW_FLAG_CUSTOM = (1UL<<2)
    -
    2564};
    -
    2565
    -
    2583HWLOC_DECLSPEC int hwloc_topology_allow(hwloc_topology_t __hwloc_restrict topology, hwloc_const_cpuset_t cpuset, hwloc_const_nodeset_t nodeset, unsigned long flags);
    -
    2584
    -
    2606HWLOC_DECLSPEC hwloc_obj_t hwloc_topology_insert_misc_object(hwloc_topology_t topology, hwloc_obj_t parent, const char *name);
    -
    2607
    -
    2618HWLOC_DECLSPEC hwloc_obj_t hwloc_topology_alloc_group_object(hwloc_topology_t topology);
    -
    2619
    -
    2666HWLOC_DECLSPEC hwloc_obj_t hwloc_topology_insert_group_object(hwloc_topology_t topology, hwloc_obj_t group);
    -
    2667
    -
    2680HWLOC_DECLSPEC int hwloc_obj_add_other_obj_sets(hwloc_obj_t dst, hwloc_obj_t src);
    -
    2681
    -
    2699HWLOC_DECLSPEC int hwloc_topology_refresh(hwloc_topology_t topology);
    -
    2700
    -
    2705#ifdef __cplusplus
    -
    2706} /* extern "C" */
    -
    2707#endif
    -
    2708
    -
    2709
    -
    2710/* high-level helpers */
    -
    2711#include "hwloc/helper.h"
    -
    2712
    -
    2713/* inline code of some functions above */
    -
    2714#include "hwloc/inlines.h"
    -
    2715
    -
    2716/* memory attributes */
    -
    2717#include "hwloc/memattrs.h"
    -
    2718
    -
    2719/* kinds of CPU cores */
    -
    2720#include "hwloc/cpukinds.h"
    -
    2721
    -
    2722/* exporting to XML or synthetic */
    -
    2723#include "hwloc/export.h"
    -
    2724
    -
    2725/* distances */
    -
    2726#include "hwloc/distances.h"
    -
    2727
    -
    2728/* topology diffs */
    -
    2729#include "hwloc/diff.h"
    -
    2730
    -
    2731/* deprecated headers */
    -
    2732#include "hwloc/deprecated.h"
    -
    2733
    -
    2734#endif /* HWLOC_H */
    -
    hwloc_get_api_version
    unsigned hwloc_get_api_version(void)
    Indicate at runtime which hwloc API version was used at build time.
    -
    hwloc_const_cpuset_t
    hwloc_const_bitmap_t hwloc_const_cpuset_t
    A non-modifiable hwloc_cpuset_t.
    Definition: hwloc.h:163
    -
    hwloc_const_nodeset_t
    hwloc_const_bitmap_t hwloc_const_nodeset_t
    A non-modifiable hwloc_nodeset_t.
    Definition: hwloc.h:181
    -
    hwloc_nodeset_t
    hwloc_bitmap_t hwloc_nodeset_t
    A node set is a bitmap whose bits are set according to NUMA memory node physical OS indexes.
    Definition: hwloc.h:178
    -
    hwloc_cpuset_t
    hwloc_bitmap_t hwloc_cpuset_t
    A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
    Definition: hwloc.h:161
    -
    hwloc_compare_types
    int hwloc_compare_types(hwloc_obj_type_t type1, hwloc_obj_type_t type2)
    Compare the depth of two object types.
    -
    hwloc_obj_bridge_type_e
    hwloc_obj_bridge_type_e
    Type of one side (upstream or downstream) of an I/O bridge.
    Definition: hwloc.h:354
    -
    hwloc_obj_cache_type_t
    enum hwloc_obj_cache_type_e hwloc_obj_cache_type_t
    Cache type.
    -
    hwloc_obj_osdev_type_e
    hwloc_obj_osdev_type_e
    Type of a OS device.
    Definition: hwloc.h:360
    -
    hwloc_obj_cache_type_e
    hwloc_obj_cache_type_e
    Cache type.
    Definition: hwloc.h:347
    -
    hwloc_obj_osdev_type_t
    enum hwloc_obj_osdev_type_e hwloc_obj_osdev_type_t
    Type of a OS device.
    -
    hwloc_obj_bridge_type_t
    enum hwloc_obj_bridge_type_e hwloc_obj_bridge_type_t
    Type of one side (upstream or downstream) of an I/O bridge.
    -
    hwloc_obj_type_t
    hwloc_obj_type_t
    Type of topology object.
    Definition: hwloc.h:197
    -
    HWLOC_OBJ_BRIDGE_HOST
    @ HWLOC_OBJ_BRIDGE_HOST
    Host-side of a bridge, only possible upstream.
    Definition: hwloc.h:355
    -
    HWLOC_OBJ_BRIDGE_PCI
    @ HWLOC_OBJ_BRIDGE_PCI
    PCI-side of a bridge.
    Definition: hwloc.h:356
    -
    HWLOC_OBJ_OSDEV_COPROC
    @ HWLOC_OBJ_OSDEV_COPROC
    Operating system co-processor device. For instance "opencl0d0" for a OpenCL device,...
    Definition: hwloc.h:374
    -
    HWLOC_OBJ_OSDEV_OPENFABRICS
    @ HWLOC_OBJ_OSDEV_OPENFABRICS
    Operating system openfabrics device. For instance the "mlx4_0" InfiniBand HCA, "hfi1_0" Omni-Path int...
    Definition: hwloc.h:368
    -
    HWLOC_OBJ_OSDEV_BLOCK
    @ HWLOC_OBJ_OSDEV_BLOCK
    Operating system block device, or non-volatile memory device. For instance "sda" or "dax2....
    Definition: hwloc.h:361
    -
    HWLOC_OBJ_OSDEV_DMA
    @ HWLOC_OBJ_OSDEV_DMA
    Operating system dma engine device. For instance the "dma0chan0" DMA channel on Linux.
    Definition: hwloc.h:372
    -
    HWLOC_OBJ_OSDEV_GPU
    @ HWLOC_OBJ_OSDEV_GPU
    Operating system GPU device. For instance ":0.0" for a GL display, "card0" for a Linux DRM device.
    Definition: hwloc.h:363
    -
    HWLOC_OBJ_OSDEV_NETWORK
    @ HWLOC_OBJ_OSDEV_NETWORK
    Operating system network device. For instance the "eth0" interface on Linux.
    Definition: hwloc.h:366
    -
    HWLOC_OBJ_CACHE_UNIFIED
    @ HWLOC_OBJ_CACHE_UNIFIED
    Unified cache.
    Definition: hwloc.h:348
    -
    HWLOC_OBJ_CACHE_INSTRUCTION
    @ HWLOC_OBJ_CACHE_INSTRUCTION
    Instruction cache (filtered out by default).
    Definition: hwloc.h:350
    -
    HWLOC_OBJ_CACHE_DATA
    @ HWLOC_OBJ_CACHE_DATA
    Data cache.
    Definition: hwloc.h:349
    -
    HWLOC_OBJ_MEMCACHE
    @ HWLOC_OBJ_MEMCACHE
    Memory-side cache (filtered out by default). A cache in front of a specific NUMA node.
    Definition: hwloc.h:326
    -
    HWLOC_OBJ_L2ICACHE
    @ HWLOC_OBJ_L2ICACHE
    Level 2 instruction Cache (filtered out by default).
    Definition: hwloc.h:241
    -
    HWLOC_OBJ_L2CACHE
    @ HWLOC_OBJ_L2CACHE
    Level 2 Data (or Unified) Cache.
    Definition: hwloc.h:235
    -
    HWLOC_OBJ_MISC
    @ HWLOC_OBJ_MISC
    Miscellaneous objects (filtered out by default). Objects without particular meaning,...
    Definition: hwloc.h:311
    -
    HWLOC_OBJ_L3CACHE
    @ HWLOC_OBJ_L3CACHE
    Level 3 Data (or Unified) Cache.
    Definition: hwloc.h:236
    -
    HWLOC_OBJ_MACHINE
    @ HWLOC_OBJ_MACHINE
    Machine. A set of processors and memory with cache coherency.
    Definition: hwloc.h:203
    -
    HWLOC_OBJ_OS_DEVICE
    @ HWLOC_OBJ_OS_DEVICE
    Operating system device (filtered out by default).
    Definition: hwloc.h:300
    -
    HWLOC_OBJ_GROUP
    @ HWLOC_OBJ_GROUP
    Group objects. Objects which do not fit in the above but are detected by hwloc and are useful to take...
    Definition: hwloc.h:244
    -
    HWLOC_OBJ_L4CACHE
    @ HWLOC_OBJ_L4CACHE
    Level 4 Data (or Unified) Cache.
    Definition: hwloc.h:237
    -
    HWLOC_OBJ_L1CACHE
    @ HWLOC_OBJ_L1CACHE
    Level 1 Data (or Unified) Cache.
    Definition: hwloc.h:234
    -
    HWLOC_OBJ_PCI_DEVICE
    @ HWLOC_OBJ_PCI_DEVICE
    PCI device (filtered out by default).
    Definition: hwloc.h:290
    -
    HWLOC_OBJ_L5CACHE
    @ HWLOC_OBJ_L5CACHE
    Level 5 Data (or Unified) Cache.
    Definition: hwloc.h:238
    -
    HWLOC_OBJ_BRIDGE
    @ HWLOC_OBJ_BRIDGE
    Bridge (filtered out by default). Any bridge (or PCI switch) that connects the host or an I/O bus,...
    Definition: hwloc.h:278
    -
    HWLOC_OBJ_NUMANODE
    @ HWLOC_OBJ_NUMANODE
    NUMA node. An object that contains memory that is directly and byte-accessible to the host processors...
    Definition: hwloc.h:257
    -
    HWLOC_OBJ_PACKAGE
    @ HWLOC_OBJ_PACKAGE
    Physical package. The physical package that usually gets inserted into a socket on the motherboard....
    Definition: hwloc.h:212
    -
    HWLOC_OBJ_PU
    @ HWLOC_OBJ_PU
    Processing Unit, or (Logical) Processor. An execution unit (may share a core with some other logical ...
    Definition: hwloc.h:222
    -
    HWLOC_OBJ_L3ICACHE
    @ HWLOC_OBJ_L3ICACHE
    Level 3 instruction Cache (filtered out by default).
    Definition: hwloc.h:242
    -
    HWLOC_OBJ_CORE
    @ HWLOC_OBJ_CORE
    Core. A computation unit (may be shared by several PUs, aka logical processors).
    Definition: hwloc.h:218
    -
    HWLOC_OBJ_DIE
    @ HWLOC_OBJ_DIE
    Die within a physical package. A subpart of the physical package, that contains multiple cores.
    Definition: hwloc.h:339
    -
    HWLOC_OBJ_L1ICACHE
    @ HWLOC_OBJ_L1ICACHE
    Level 1 instruction Cache (filtered out by default).
    Definition: hwloc.h:240
    -
    hwloc_obj_t
    struct hwloc_obj * hwloc_obj_t
    Convenience typedef; a pointer to a struct hwloc_obj.
    Definition: hwloc.h:620
    -
    hwloc_topology_init
    int hwloc_topology_init(hwloc_topology_t *topologyp)
    Allocate a topology context.
    -
    hwloc_topology_abi_check
    int hwloc_topology_abi_check(hwloc_topology_t topology)
    Verify that the topology is compatible with the current hwloc library.
    -
    hwloc_topology_dup
    int hwloc_topology_dup(hwloc_topology_t *newtopology, hwloc_topology_t oldtopology)
    Duplicate a topology.
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:716
    -
    hwloc_topology_destroy
    void hwloc_topology_destroy(hwloc_topology_t topology)
    Terminate and free a topology context.
    -
    hwloc_topology_load
    int hwloc_topology_load(hwloc_topology_t topology)
    Build the actual topology.
    -
    hwloc_topology_check
    void hwloc_topology_check(hwloc_topology_t topology)
    Run internal checks on a topology structure.
    -
    hwloc_get_nbobjs_by_depth
    unsigned hwloc_get_nbobjs_by_depth(hwloc_topology_t topology, int depth)
    Returns the width of level at depth depth.
    -
    hwloc_get_root_obj
    static hwloc_obj_t hwloc_get_root_obj(hwloc_topology_t topology)
    Returns the top-object of the topology-tree.
    -
    hwloc_get_obj_by_depth
    hwloc_obj_t hwloc_get_obj_by_depth(hwloc_topology_t topology, int depth, unsigned idx)
    Returns the topology object at logical index idx from depth depth.
    -
    hwloc_get_depth_type
    hwloc_obj_type_t hwloc_get_depth_type(hwloc_topology_t topology, int depth)
    Returns the type of objects at depth depth.
    -
    hwloc_get_obj_by_type
    static hwloc_obj_t hwloc_get_obj_by_type(hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx)
    Returns the topology object at logical index idx with type type.
    -
    hwloc_get_next_obj_by_type
    static hwloc_obj_t hwloc_get_next_obj_by_type(hwloc_topology_t topology, hwloc_obj_type_t type, hwloc_obj_t prev)
    Returns the next object of type type.
    -
    hwloc_get_nbobjs_by_type
    static int hwloc_get_nbobjs_by_type(hwloc_topology_t topology, hwloc_obj_type_t type)
    Returns the width of level type type.
    -
    hwloc_get_type_or_below_depth
    static int hwloc_get_type_or_below_depth(hwloc_topology_t topology, hwloc_obj_type_t type)
    Returns the depth of objects of type type or below.
    -
    hwloc_get_type_or_above_depth
    static int hwloc_get_type_or_above_depth(hwloc_topology_t topology, hwloc_obj_type_t type)
    Returns the depth of objects of type type or above.
    -
    hwloc_get_type_depth
    int hwloc_get_type_depth(hwloc_topology_t topology, hwloc_obj_type_t type)
    Returns the depth of objects of type type.
    -
    hwloc_get_next_obj_by_depth
    static hwloc_obj_t hwloc_get_next_obj_by_depth(hwloc_topology_t topology, int depth, hwloc_obj_t prev)
    Returns the next object at depth depth.
    -
    hwloc_topology_get_depth
    int hwloc_topology_get_depth(hwloc_topology_t restrict topology)
    Get the depth of the hierarchical tree of objects.
    -
    hwloc_get_memory_parents_depth
    int hwloc_get_memory_parents_depth(hwloc_topology_t topology)
    Return the depth of parents where memory objects are attached.
    -
    hwloc_get_type_depth_e
    hwloc_get_type_depth_e
    Definition: hwloc.h:852
    -
    HWLOC_TYPE_DEPTH_UNKNOWN
    @ HWLOC_TYPE_DEPTH_UNKNOWN
    No object of given type exists in the topology.
    Definition: hwloc.h:853
    -
    HWLOC_TYPE_DEPTH_NUMANODE
    @ HWLOC_TYPE_DEPTH_NUMANODE
    Virtual depth for NUMA nodes.
    Definition: hwloc.h:855
    -
    HWLOC_TYPE_DEPTH_MEMCACHE
    @ HWLOC_TYPE_DEPTH_MEMCACHE
    Virtual depth for MemCache object.
    Definition: hwloc.h:860
    -
    HWLOC_TYPE_DEPTH_MISC
    @ HWLOC_TYPE_DEPTH_MISC
    Virtual depth for Misc object.
    Definition: hwloc.h:859
    -
    HWLOC_TYPE_DEPTH_PCI_DEVICE
    @ HWLOC_TYPE_DEPTH_PCI_DEVICE
    Virtual depth for PCI device object level.
    Definition: hwloc.h:857
    -
    HWLOC_TYPE_DEPTH_MULTIPLE
    @ HWLOC_TYPE_DEPTH_MULTIPLE
    Objects of given type exist at different depth in the topology (only for Groups).
    Definition: hwloc.h:854
    -
    HWLOC_TYPE_DEPTH_BRIDGE
    @ HWLOC_TYPE_DEPTH_BRIDGE
    Virtual depth for bridge object level.
    Definition: hwloc.h:856
    -
    HWLOC_TYPE_DEPTH_OS_DEVICE
    @ HWLOC_TYPE_DEPTH_OS_DEVICE
    Virtual depth for software device object level.
    Definition: hwloc.h:858
    -
    hwloc_type_sscanf
    int hwloc_type_sscanf(const char *string, hwloc_obj_type_t *typep, union hwloc_obj_attr_u *attrp, size_t attrsize)
    Return an object type and attributes from a type string.
    -
    hwloc_type_sscanf_as_depth
    int hwloc_type_sscanf_as_depth(const char *string, hwloc_obj_type_t *typep, hwloc_topology_t topology, int *depthp)
    Return an object type and its level depth from a type string.
    -
    hwloc_obj_type_string
    const char * hwloc_obj_type_string(hwloc_obj_type_t type)
    Return a constant stringified object type.
    -
    hwloc_obj_attr_snprintf
    int hwloc_obj_attr_snprintf(char *restrict string, size_t size, hwloc_obj_t obj, const char *restrict separator, int verbose)
    Stringify the attributes of a given topology object into a human-readable form.
    -
    hwloc_obj_type_snprintf
    int hwloc_obj_type_snprintf(char *restrict string, size_t size, hwloc_obj_t obj, int verbose)
    Stringify the type of a given topology object into a human-readable form.
    -
    hwloc_obj_get_info_by_name
    static const char * hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name)
    Search the given key name in object infos and return the corresponding value.
    -
    hwloc_obj_add_info
    int hwloc_obj_add_info(hwloc_obj_t obj, const char *name, const char *value)
    Add the given info name and value pair to the given object.
    -
    hwloc_cpubind_flags_t
    hwloc_cpubind_flags_t
    Process/Thread binding flags.
    Definition: hwloc.h:1207
    -
    hwloc_set_proc_cpubind
    int hwloc_set_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_cpuset_t set, int flags)
    Bind a process pid on CPUs given in physical bitmap set.
    -
    hwloc_set_cpubind
    int hwloc_set_cpubind(hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags)
    Bind current process or thread on CPUs given in physical bitmap set.
    -
    hwloc_get_proc_last_cpu_location
    int hwloc_get_proc_last_cpu_location(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags)
    Get the last physical CPU where a process ran.
    -
    hwloc_get_proc_cpubind
    int hwloc_get_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags)
    Get the current physical binding of process pid.
    -
    hwloc_get_cpubind
    int hwloc_get_cpubind(hwloc_topology_t topology, hwloc_cpuset_t set, int flags)
    Get current process or thread binding.
    -
    hwloc_set_thread_cpubind
    int hwloc_set_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_const_cpuset_t set, int flags)
    Bind a thread thread on CPUs given in physical bitmap set.
    -
    hwloc_get_thread_cpubind
    int hwloc_get_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_cpuset_t set, int flags)
    Get the current physical binding of thread tid.
    -
    hwloc_get_last_cpu_location
    int hwloc_get_last_cpu_location(hwloc_topology_t topology, hwloc_cpuset_t set, int flags)
    Get the last physical CPU where the current process or thread ran.
    -
    HWLOC_CPUBIND_PROCESS
    @ HWLOC_CPUBIND_PROCESS
    Bind all threads of the current (possibly) multithreaded process.
    Definition: hwloc.h:1210
    -
    HWLOC_CPUBIND_NOMEMBIND
    @ HWLOC_CPUBIND_NOMEMBIND
    Avoid any effect on memory binding.
    Definition: hwloc.h:1256
    -
    HWLOC_CPUBIND_STRICT
    @ HWLOC_CPUBIND_STRICT
    Request for strict binding from the OS.
    Definition: hwloc.h:1239
    -
    HWLOC_CPUBIND_THREAD
    @ HWLOC_CPUBIND_THREAD
    Bind current thread of current process.
    Definition: hwloc.h:1214
    -
    hwloc_set_membind
    int hwloc_set_membind(hwloc_topology_t topology, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags)
    Set the default memory binding policy of the current process or thread to prefer the NUMA node(s) spe...
    -
    hwloc_get_proc_membind
    int hwloc_get_proc_membind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_bitmap_t set, hwloc_membind_policy_t *policy, int flags)
    Query the default memory binding policy and physical locality of the specified process.
    -
    hwloc_free
    int hwloc_free(hwloc_topology_t topology, void *addr, size_t len)
    Free memory that was previously allocated by hwloc_alloc() or hwloc_alloc_membind().
    -
    hwloc_get_area_memlocation
    int hwloc_get_area_memlocation(hwloc_topology_t topology, const void *addr, size_t len, hwloc_bitmap_t set, int flags)
    Get the NUMA nodes where memory identified by (addr, len ) is physically allocated.
    -
    hwloc_alloc_membind_policy
    static void * hwloc_alloc_membind_policy(hwloc_topology_t topology, size_t len, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags)
    Allocate some memory on NUMA memory nodes specified by set.
    -
    hwloc_alloc
    void * hwloc_alloc(hwloc_topology_t topology, size_t len)
    Allocate some memory.
    -
    hwloc_get_area_membind
    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)
    Query the CPUs near the physical NUMA node(s) and binding policy of the memory identified by (addr,...
    -
    hwloc_membind_flags_t
    hwloc_membind_flags_t
    Memory binding flags.
    Definition: hwloc.h:1528
    -
    hwloc_set_proc_membind
    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)
    Set the default memory binding policy of the specified process to prefer the NUMA node(s) specified b...
    -
    hwloc_membind_policy_t
    hwloc_membind_policy_t
    Memory binding policy.
    Definition: hwloc.h:1465
    -
    hwloc_alloc_membind
    void * hwloc_alloc_membind(hwloc_topology_t topology, size_t len, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags)
    Allocate some memory on NUMA memory nodes specified by set.
    -
    hwloc_get_membind
    int hwloc_get_membind(hwloc_topology_t topology, hwloc_bitmap_t set, hwloc_membind_policy_t *policy, int flags)
    Query the default memory binding policy and physical locality of the current process or thread.
    -
    hwloc_set_area_membind
    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)
    Bind the already-allocated memory identified by (addr, len) to the NUMA node(s) specified by set.
    -
    HWLOC_MEMBIND_STRICT
    @ HWLOC_MEMBIND_STRICT
    Definition: hwloc.h:1546
    -
    HWLOC_MEMBIND_PROCESS
    @ HWLOC_MEMBIND_PROCESS
    Set policy for all threads of the specified (possibly multithreaded) process. This flag is mutually e...
    Definition: hwloc.h:1533
    -
    HWLOC_MEMBIND_THREAD
    @ HWLOC_MEMBIND_THREAD
    Set policy for a specific thread of the current process. This flag is mutually exclusive with HWLOC_M...
    Definition: hwloc.h:1538
    -
    HWLOC_MEMBIND_BYNODESET
    @ HWLOC_MEMBIND_BYNODESET
    Consider the bitmap argument as a nodeset.
    Definition: hwloc.h:1576
    -
    HWLOC_MEMBIND_MIGRATE
    @ HWLOC_MEMBIND_MIGRATE
    Migrate existing allocated memory. If the memory cannot be migrated and the HWLOC_MEMBIND_STRICT flag...
    Definition: hwloc.h:1552
    -
    HWLOC_MEMBIND_NOCPUBIND
    @ HWLOC_MEMBIND_NOCPUBIND
    Avoid any effect on CPU binding.
    Definition: hwloc.h:1565
    -
    HWLOC_MEMBIND_DEFAULT
    @ HWLOC_MEMBIND_DEFAULT
    Reset the memory allocation policy to the system default. Depending on the operating system,...
    Definition: hwloc.h:1473
    -
    HWLOC_MEMBIND_MIXED
    @ HWLOC_MEMBIND_MIXED
    Returned by get_membind() functions when multiple threads or parts of a memory area have differing me...
    Definition: hwloc.h:1512
    -
    HWLOC_MEMBIND_FIRSTTOUCH
    @ HWLOC_MEMBIND_FIRSTTOUCH
    Allocate each memory page individually on the local NUMA node of the thread that touches it.
    Definition: hwloc.h:1484
    -
    HWLOC_MEMBIND_BIND
    @ HWLOC_MEMBIND_BIND
    Allocate memory on the specified nodes.
    Definition: hwloc.h:1488
    -
    HWLOC_MEMBIND_INTERLEAVE
    @ HWLOC_MEMBIND_INTERLEAVE
    Allocate memory on the given nodes in an interleaved / round-robin manner. The precise layout of the ...
    Definition: hwloc.h:1497
    -
    HWLOC_MEMBIND_NEXTTOUCH
    @ HWLOC_MEMBIND_NEXTTOUCH
    For each page bound with this policy, by next time it is touched (and next time only),...
    Definition: hwloc.h:1504
    -
    hwloc_topology_set_xmlbuffer
    int hwloc_topology_set_xmlbuffer(hwloc_topology_t restrict topology, const char *restrict buffer, int size)
    Enable XML based topology using a memory buffer (instead of a file, as with hwloc_topology_set_xml())...
    -
    hwloc_topology_set_pid
    int hwloc_topology_set_pid(hwloc_topology_t restrict topology, hwloc_pid_t pid)
    Change which process the topology is viewed from.
    -
    hwloc_topology_set_synthetic
    int hwloc_topology_set_synthetic(hwloc_topology_t restrict topology, const char *restrict description)
    Enable synthetic topology.
    -
    hwloc_topology_set_xml
    int hwloc_topology_set_xml(hwloc_topology_t restrict topology, const char *restrict xmlpath)
    Enable XML-file based topology.
    -
    hwloc_topology_components_flag_e
    hwloc_topology_components_flag_e
    Flags to be passed to hwloc_topology_set_components()
    Definition: hwloc.h:1966
    -
    hwloc_topology_set_components
    int hwloc_topology_set_components(hwloc_topology_t restrict topology, unsigned long flags, const char *restrict name)
    Prevent a discovery component from being used for a topology.
    -
    HWLOC_TOPOLOGY_COMPONENTS_FLAG_BLACKLIST
    @ HWLOC_TOPOLOGY_COMPONENTS_FLAG_BLACKLIST
    Blacklist the target component from being used.
    Definition: hwloc.h:1970
    -
    hwloc_topology_get_flags
    unsigned long hwloc_topology_get_flags(hwloc_topology_t topology)
    Get OR'ed flags of a topology.
    -
    hwloc_topology_set_io_types_filter
    int hwloc_topology_set_io_types_filter(hwloc_topology_t topology, enum hwloc_type_filter_e filter)
    Set the filtering for all I/O object types.
    -
    hwloc_topology_get_type_filter
    int hwloc_topology_get_type_filter(hwloc_topology_t topology, hwloc_obj_type_t type, enum hwloc_type_filter_e *filter)
    Get the current filtering for the given object type.
    -
    hwloc_topology_set_userdata
    void hwloc_topology_set_userdata(hwloc_topology_t topology, const void *userdata)
    Set the topology-specific userdata pointer.
    -
    hwloc_topology_set_cache_types_filter
    int hwloc_topology_set_cache_types_filter(hwloc_topology_t topology, enum hwloc_type_filter_e filter)
    Set the filtering for all CPU cache object types.
    -
    hwloc_topology_set_icache_types_filter
    int hwloc_topology_set_icache_types_filter(hwloc_topology_t topology, enum hwloc_type_filter_e filter)
    Set the filtering for all CPU instruction cache object types.
    -
    hwloc_topology_is_thissystem
    int hwloc_topology_is_thissystem(hwloc_topology_t restrict topology)
    Does the topology context come from this system?
    -
    hwloc_type_filter_e
    hwloc_type_filter_e
    Type filtering flags.
    Definition: hwloc.h:2365
    -
    hwloc_topology_set_all_types_filter
    int hwloc_topology_set_all_types_filter(hwloc_topology_t topology, enum hwloc_type_filter_e filter)
    Set the filtering for all object types.
    -
    hwloc_topology_set_flags
    int hwloc_topology_set_flags(hwloc_topology_t topology, unsigned long flags)
    Set OR'ed flags to non-yet-loaded topology.
    -
    hwloc_topology_get_support
    const struct hwloc_topology_support * hwloc_topology_get_support(hwloc_topology_t restrict topology)
    Retrieve the topology support.
    -
    hwloc_topology_get_userdata
    void * hwloc_topology_get_userdata(hwloc_topology_t topology)
    Retrieve the topology-specific userdata pointer.
    -
    hwloc_topology_set_type_filter
    int hwloc_topology_set_type_filter(hwloc_topology_t topology, hwloc_obj_type_t type, enum hwloc_type_filter_e filter)
    Set the filtering for the given object type.
    -
    hwloc_topology_flags_e
    hwloc_topology_flags_e
    Flags to be set onto a topology context before load.
    Definition: hwloc.h:2010
    -
    HWLOC_TYPE_FILTER_KEEP_NONE
    @ HWLOC_TYPE_FILTER_KEEP_NONE
    Ignore all objects of this type.
    Definition: hwloc.h:2379
    -
    HWLOC_TYPE_FILTER_KEEP_IMPORTANT
    @ HWLOC_TYPE_FILTER_KEEP_IMPORTANT
    Only keep likely-important objects of the given type.
    Definition: hwloc.h:2408
    -
    HWLOC_TYPE_FILTER_KEEP_STRUCTURE
    @ HWLOC_TYPE_FILTER_KEEP_STRUCTURE
    Only ignore objects if their entire level does not bring any structure.
    Definition: hwloc.h:2393
    -
    HWLOC_TYPE_FILTER_KEEP_ALL
    @ HWLOC_TYPE_FILTER_KEEP_ALL
    Keep all objects of this type.
    Definition: hwloc.h:2371
    -
    HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED
    @ HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED
    Detect the whole system, ignore reservations, include disallowed objects.
    Definition: hwloc.h:2032
    -
    HWLOC_TOPOLOGY_FLAG_THISSYSTEM_ALLOWED_RESOURCES
    @ HWLOC_TOPOLOGY_FLAG_THISSYSTEM_ALLOWED_RESOURCES
    Get the set of allowed resources from the local operating system even if the topology was loaded from...
    Definition: hwloc.h:2073
    -
    HWLOC_TOPOLOGY_FLAG_NO_CPUKINDS
    @ HWLOC_TOPOLOGY_FLAG_NO_CPUKINDS
    Ignore CPU Kinds.
    Definition: hwloc.h:2178
    -
    HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_MEMBINDING
    @ HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_MEMBINDING
    Do not consider resources outside of the process memory binding.
    Definition: hwloc.h:2144
    -
    HWLOC_TOPOLOGY_FLAG_NO_DISTANCES
    @ HWLOC_TOPOLOGY_FLAG_NO_DISTANCES
    Ignore distances.
    Definition: hwloc.h:2166
    -
    HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM
    @ HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM
    Assume that the selected backend provides the topology for the system on which we are running.
    Definition: hwloc.h:2052
    -
    HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_CPUBINDING
    @ HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_CPUBINDING
    Do not consider resources outside of the process CPU binding.
    Definition: hwloc.h:2122
    -
    HWLOC_TOPOLOGY_FLAG_NO_MEMATTRS
    @ HWLOC_TOPOLOGY_FLAG_NO_MEMATTRS
    Ignore memory attributes.
    Definition: hwloc.h:2172
    -
    HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT
    @ HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT
    Import support from the imported topology.
    Definition: hwloc.h:2097
    -
    HWLOC_TOPOLOGY_FLAG_DONT_CHANGE_BINDING
    @ HWLOC_TOPOLOGY_FLAG_DONT_CHANGE_BINDING
    Do not ever modify the process or thread binding during discovery.
    Definition: hwloc.h:2159
    -
    hwloc_topology_insert_group_object
    hwloc_obj_t hwloc_topology_insert_group_object(hwloc_topology_t topology, hwloc_obj_t group)
    Add more structure to the topology by adding an intermediate Group.
    -
    hwloc_allow_flags_e
    hwloc_allow_flags_e
    Flags to be given to hwloc_topology_allow().
    Definition: hwloc.h:2545
    -
    hwloc_topology_alloc_group_object
    hwloc_obj_t hwloc_topology_alloc_group_object(hwloc_topology_t topology)
    Allocate a Group object to insert later with hwloc_topology_insert_group_object().
    -
    hwloc_topology_refresh
    int hwloc_topology_refresh(hwloc_topology_t topology)
    Refresh internal structures after topology modification.
    -
    hwloc_topology_restrict
    int hwloc_topology_restrict(hwloc_topology_t restrict topology, hwloc_const_bitmap_t set, unsigned long flags)
    Restrict the topology to the given CPU set or nodeset.
    -
    hwloc_restrict_flags_e
    hwloc_restrict_flags_e
    Flags to be given to hwloc_topology_restrict().
    Definition: hwloc.h:2484
    -
    hwloc_obj_add_other_obj_sets
    int hwloc_obj_add_other_obj_sets(hwloc_obj_t dst, hwloc_obj_t src)
    Setup object cpusets/nodesets by OR'ing another object's sets.
    -
    hwloc_topology_insert_misc_object
    hwloc_obj_t hwloc_topology_insert_misc_object(hwloc_topology_t topology, hwloc_obj_t parent, const char *name)
    Add a MISC object as a leaf of the topology.
    -
    hwloc_topology_allow
    int hwloc_topology_allow(hwloc_topology_t restrict topology, hwloc_const_cpuset_t cpuset, hwloc_const_nodeset_t nodeset, unsigned long flags)
    Change the sets of allowed PUs and NUMA nodes in the topology.
    -
    HWLOC_ALLOW_FLAG_CUSTOM
    @ HWLOC_ALLOW_FLAG_CUSTOM
    Allow a custom set of objects, given to hwloc_topology_allow() as cpuset and/or nodeset parameters.
    Definition: hwloc.h:2563
    -
    HWLOC_ALLOW_FLAG_LOCAL_RESTRICTIONS
    @ HWLOC_ALLOW_FLAG_LOCAL_RESTRICTIONS
    Only allow objects that are available to the current process.
    Definition: hwloc.h:2559
    -
    HWLOC_ALLOW_FLAG_ALL
    @ HWLOC_ALLOW_FLAG_ALL
    Mark all objects as allowed in the topology.
    Definition: hwloc.h:2550
    -
    HWLOC_RESTRICT_FLAG_ADAPT_MISC
    @ HWLOC_RESTRICT_FLAG_ADAPT_MISC
    Move Misc objects to ancestors if their parents are removed during restriction. If this flag is not s...
    Definition: hwloc.h:2509
    -
    HWLOC_RESTRICT_FLAG_REMOVE_CPULESS
    @ HWLOC_RESTRICT_FLAG_REMOVE_CPULESS
    Remove all objects that became CPU-less. By default, only objects that contain no PU and no memory ar...
    Definition: hwloc.h:2490
    -
    HWLOC_RESTRICT_FLAG_ADAPT_IO
    @ HWLOC_RESTRICT_FLAG_ADAPT_IO
    Move I/O objects to ancestors if their parents are removed during restriction. If this flag is not se...
    Definition: hwloc.h:2515
    -
    HWLOC_RESTRICT_FLAG_BYNODESET
    @ HWLOC_RESTRICT_FLAG_BYNODESET
    Restrict by nodeset instead of CPU set. Only keep objects whose nodeset is included or partially incl...
    Definition: hwloc.h:2496
    -
    HWLOC_RESTRICT_FLAG_REMOVE_MEMLESS
    @ HWLOC_RESTRICT_FLAG_REMOVE_MEMLESS
    Remove all objects that became Memory-less. By default, only objects that contain no PU and no memory...
    Definition: hwloc.h:2503
    -
    hwloc_bitmap_t
    struct hwloc_bitmap_s * hwloc_bitmap_t
    Set of bits represented as an opaque pointer to an internal bitmap.
    Definition: bitmap.h:69
    -
    hwloc_const_bitmap_t
    const struct hwloc_bitmap_s * hwloc_const_bitmap_t
    a non-modifiable hwloc_bitmap_t
    Definition: bitmap.h:71
    -
    hwloc_obj
    Structure of a topology object.
    Definition: hwloc.h:420
    -
    hwloc_obj::children
    struct hwloc_obj ** children
    Normal children, children[0 .. arity -1].
    Definition: hwloc.h:480
    -
    hwloc_obj::nodeset
    hwloc_nodeset_t nodeset
    NUMA nodes covered by this object or containing this object.
    Definition: hwloc.h:564
    -
    hwloc_obj::logical_index
    unsigned logical_index
    Horizontal index in the whole list of similar objects, hence guaranteed unique across the entire mach...
    Definition: hwloc.h:458
    -
    hwloc_obj::symmetric_subtree
    int symmetric_subtree
    Set if the subtree of normal objects below this object is symmetric, which means all normal children ...
    Definition: hwloc.h:485
    -
    hwloc_obj::misc_arity
    unsigned misc_arity
    Number of Misc children. These children are listed in misc_first_child.
    Definition: hwloc.h:526
    -
    hwloc_obj::depth
    int depth
    Vertical index in the hierarchy.
    Definition: hwloc.h:443
    -
    hwloc_obj::misc_first_child
    struct hwloc_obj * misc_first_child
    First Misc child. Misc objects are listed here (misc_arity and misc_first_child) instead of in the no...
    Definition: hwloc.h:529
    -
    hwloc_obj::subtype
    char * subtype
    Subtype string to better describe the type field.
    Definition: hwloc.h:423
    -
    hwloc_obj::os_index
    unsigned os_index
    OS-provided physical index number. It is not guaranteed unique across the entire machine,...
    Definition: hwloc.h:425
    -
    hwloc_obj::cpuset
    hwloc_cpuset_t cpuset
    CPUs covered by this object.
    Definition: hwloc.h:536
    -
    hwloc_obj::memory_arity
    unsigned memory_arity
    Number of Memory children. These children are listed in memory_first_child.
    Definition: hwloc.h:496
    -
    hwloc_obj::total_memory
    hwloc_uint64_t total_memory
    Total memory (in bytes) in NUMA nodes below this object.
    Definition: hwloc.h:437
    -
    hwloc_obj::userdata
    void * userdata
    Application-given private data pointer, initialized to NULL, use it as you wish. See hwloc_topology_s...
    Definition: hwloc.h:606
    -
    hwloc_obj::io_arity
    unsigned io_arity
    Number of I/O children. These children are listed in io_first_child.
    Definition: hwloc.h:514
    -
    hwloc_obj::prev_sibling
    struct hwloc_obj * prev_sibling
    Previous object below the same parent (inside the same list of children).
    Definition: hwloc.h:473
    -
    hwloc_obj::next_sibling
    struct hwloc_obj * next_sibling
    Next object below the same parent (inside the same list of children).
    Definition: hwloc.h:472
    -
    hwloc_obj::last_child
    struct hwloc_obj * last_child
    Last normal child.
    Definition: hwloc.h:482
    -
    hwloc_obj::next_cousin
    struct hwloc_obj * next_cousin
    Next object of same type and depth.
    Definition: hwloc.h:466
    -
    hwloc_obj::infos
    struct hwloc_info_s * infos
    Array of stringified info type=name.
    Definition: hwloc.h:602
    -
    hwloc_obj::io_first_child
    struct hwloc_obj * io_first_child
    First I/O child. Bridges, PCI and OS devices are listed here (io_arity and io_first_child) instead of...
    Definition: hwloc.h:517
    -
    hwloc_obj::complete_cpuset
    hwloc_cpuset_t complete_cpuset
    The complete CPU set of processors of this object,.
    Definition: hwloc.h:551
    -
    hwloc_obj::gp_index
    hwloc_uint64_t gp_index
    Global persistent index. Generated by hwloc, unique across the topology (contrary to os_index) and pe...
    Definition: hwloc.h:611
    -
    hwloc_obj::infos_count
    unsigned infos_count
    Size of infos array.
    Definition: hwloc.h:603
    -
    hwloc_obj::sibling_rank
    unsigned sibling_rank
    Index in parent's children[] array. Or the index in parent's Memory, I/O or Misc children list.
    Definition: hwloc.h:471
    -
    hwloc_obj::arity
    unsigned arity
    Number of normal children. Memory, Misc and I/O children are not listed here but rather in their dedi...
    Definition: hwloc.h:476
    -
    hwloc_obj::name
    char * name
    Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name str...
    Definition: hwloc.h:432
    -
    hwloc_obj::memory_first_child
    struct hwloc_obj * memory_first_child
    First Memory child. NUMA nodes and Memory-side caches are listed here (memory_arity and memory_first_...
    Definition: hwloc.h:499
    -
    hwloc_obj::complete_nodeset
    hwloc_nodeset_t complete_nodeset
    The complete NUMA node set of this object,.
    Definition: hwloc.h:586
    -
    hwloc_obj::prev_cousin
    struct hwloc_obj * prev_cousin
    Previous object of same type and depth.
    Definition: hwloc.h:467
    -
    hwloc_obj::type
    hwloc_obj_type_t type
    Type of object.
    Definition: hwloc.h:422
    -
    hwloc_obj::attr
    union hwloc_obj_attr_u * attr
    Object type-specific Attributes, may be NULL if no attribute value was found.
    Definition: hwloc.h:439
    -
    hwloc_obj::parent
    struct hwloc_obj * parent
    Parent, NULL if root (Machine object)
    Definition: hwloc.h:470
    -
    hwloc_obj::first_child
    struct hwloc_obj * first_child
    First normal child.
    Definition: hwloc.h:481
    -
    hwloc_obj_attr_u
    Object type-specific Attributes.
    Definition: hwloc.h:623
    -
    hwloc_obj_attr_u::pcidev
    struct hwloc_obj_attr_u::hwloc_pcidev_attr_s pcidev
    -
    hwloc_obj_attr_u::bridge
    struct hwloc_obj_attr_u::hwloc_bridge_attr_s bridge
    -
    hwloc_obj_attr_u::cache
    struct hwloc_obj_attr_u::hwloc_cache_attr_s cache
    -
    hwloc_obj_attr_u::group
    struct hwloc_obj_attr_u::hwloc_group_attr_s group
    -
    hwloc_obj_attr_u::osdev
    struct hwloc_obj_attr_u::hwloc_osdev_attr_s osdev
    -
    hwloc_obj_attr_u::numanode
    struct hwloc_obj_attr_u::hwloc_numanode_attr_s numanode
    -
    hwloc_obj_attr_u::hwloc_numanode_attr_s
    NUMA node-specific Object Attributes.
    Definition: hwloc.h:625
    -
    hwloc_obj_attr_u::hwloc_numanode_attr_s::page_types_len
    unsigned page_types_len
    Size of array page_types.
    Definition: hwloc.h:627
    -
    hwloc_obj_attr_u::hwloc_numanode_attr_s::local_memory
    hwloc_uint64_t local_memory
    Local memory (in bytes)
    Definition: hwloc.h:626
    -
    hwloc_obj_attr_u::hwloc_numanode_attr_s::page_types
    struct hwloc_obj_attr_u::hwloc_numanode_attr_s::hwloc_memory_page_type_s * page_types
    -
    hwloc_obj_attr_u::hwloc_numanode_attr_s::hwloc_memory_page_type_s
    Array of local memory page types, NULL if no local memory and page_types is 0.
    Definition: hwloc.h:633
    -
    hwloc_obj_attr_u::hwloc_numanode_attr_s::hwloc_memory_page_type_s::size
    hwloc_uint64_t size
    Size of pages.
    Definition: hwloc.h:634
    -
    hwloc_obj_attr_u::hwloc_numanode_attr_s::hwloc_memory_page_type_s::count
    hwloc_uint64_t count
    Number of pages of this size.
    Definition: hwloc.h:635
    -
    hwloc_obj_attr_u::hwloc_cache_attr_s
    Cache-specific Object Attributes.
    Definition: hwloc.h:640
    -
    hwloc_obj_attr_u::hwloc_cache_attr_s::depth
    unsigned depth
    Depth of cache (e.g., L1, L2, ...etc.)
    Definition: hwloc.h:642
    -
    hwloc_obj_attr_u::hwloc_cache_attr_s::linesize
    unsigned linesize
    Cache-line size in bytes. 0 if unknown.
    Definition: hwloc.h:643
    -
    hwloc_obj_attr_u::hwloc_cache_attr_s::size
    hwloc_uint64_t size
    Size of cache in bytes.
    Definition: hwloc.h:641
    -
    hwloc_obj_attr_u::hwloc_cache_attr_s::associativity
    int associativity
    Ways of associativity, -1 if fully associative, 0 if unknown.
    Definition: hwloc.h:644
    -
    hwloc_obj_attr_u::hwloc_cache_attr_s::type
    hwloc_obj_cache_type_t type
    Cache type.
    Definition: hwloc.h:646
    -
    hwloc_obj_attr_u::hwloc_group_attr_s
    Group-specific Object Attributes.
    Definition: hwloc.h:649
    -
    hwloc_obj_attr_u::hwloc_group_attr_s::kind
    unsigned kind
    Internally-used kind of group.
    Definition: hwloc.h:652
    -
    hwloc_obj_attr_u::hwloc_group_attr_s::subkind
    unsigned subkind
    Internally-used subkind to distinguish different levels of groups with same kind.
    Definition: hwloc.h:653
    -
    hwloc_obj_attr_u::hwloc_group_attr_s::depth
    unsigned depth
    Depth of group object. It may change if intermediate Group objects are added.
    Definition: hwloc.h:650
    -
    hwloc_obj_attr_u::hwloc_group_attr_s::dont_merge
    unsigned char dont_merge
    Flag preventing groups from being automatically merged with identical parent or children.
    Definition: hwloc.h:654
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s
    PCI Device specific Object Attributes.
    Definition: hwloc.h:657
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::revision
    unsigned char revision
    Definition: hwloc.h:666
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::device_id
    unsigned short device_id
    Definition: hwloc.h:665
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::dev
    unsigned char dev
    Definition: hwloc.h:663
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::subvendor_id
    unsigned short subvendor_id
    Definition: hwloc.h:665
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::linkspeed
    float linkspeed
    Definition: hwloc.h:667
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::func
    unsigned char func
    Definition: hwloc.h:663
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::domain
    unsigned short domain
    Definition: hwloc.h:659
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::vendor_id
    unsigned short vendor_id
    Definition: hwloc.h:665
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::bus
    unsigned char bus
    Definition: hwloc.h:663
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::subdevice_id
    unsigned short subdevice_id
    Definition: hwloc.h:665
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::class_id
    unsigned short class_id
    Definition: hwloc.h:664
    -
    hwloc_obj_attr_u::hwloc_bridge_attr_s
    Bridge specific Object Attributes.
    Definition: hwloc.h:670
    -
    hwloc_obj_attr_u::hwloc_bridge_attr_s::upstream_type
    hwloc_obj_bridge_type_t upstream_type
    Definition: hwloc.h:674
    -
    hwloc_obj_attr_u::hwloc_bridge_attr_s::domain
    unsigned short domain
    Definition: hwloc.h:678
    -
    hwloc_obj_attr_u::hwloc_bridge_attr_s::depth
    unsigned depth
    Definition: hwloc.h:686
    -
    hwloc_obj_attr_u::hwloc_bridge_attr_s::downstream
    union hwloc_obj_attr_u::hwloc_bridge_attr_s::@1 downstream
    -
    hwloc_obj_attr_u::hwloc_bridge_attr_s::pci
    struct hwloc_pcidev_attr_s pci
    Definition: hwloc.h:672
    -
    hwloc_obj_attr_u::hwloc_bridge_attr_s::upstream
    union hwloc_obj_attr_u::hwloc_bridge_attr_s::@0 upstream
    -
    hwloc_obj_attr_u::hwloc_bridge_attr_s::downstream_type
    hwloc_obj_bridge_type_t downstream_type
    Definition: hwloc.h:685
    -
    hwloc_obj_attr_u::hwloc_bridge_attr_s::secondary_bus
    unsigned char secondary_bus
    Definition: hwloc.h:682
    -
    hwloc_obj_attr_u::hwloc_bridge_attr_s::subordinate_bus
    unsigned char subordinate_bus
    Definition: hwloc.h:682
    -
    hwloc_obj_attr_u::hwloc_osdev_attr_s
    OS Device specific Object Attributes.
    Definition: hwloc.h:689
    -
    hwloc_obj_attr_u::hwloc_osdev_attr_s::type
    hwloc_obj_osdev_type_t type
    Definition: hwloc.h:690
    -
    hwloc_info_s
    Object info.
    Definition: hwloc.h:698
    -
    hwloc_info_s::name
    char * name
    Info name.
    Definition: hwloc.h:699
    -
    hwloc_info_s::value
    char * value
    Info value.
    Definition: hwloc.h:700
    -
    hwloc_topology_discovery_support
    Flags describing actual discovery support for this topology.
    Definition: hwloc.h:2222
    -
    hwloc_topology_discovery_support::numa
    unsigned char numa
    Detecting the number of NUMA nodes is supported.
    Definition: hwloc.h:2226
    -
    hwloc_topology_discovery_support::disallowed_numa
    unsigned char disallowed_numa
    Detecting and identifying NUMA nodes that are not available to the current process is supported.
    Definition: hwloc.h:2232
    -
    hwloc_topology_discovery_support::cpukind_efficiency
    unsigned char cpukind_efficiency
    Detecting the efficiency of CPU kinds is supported, see Kinds of CPU cores.
    Definition: hwloc.h:2234
    -
    hwloc_topology_discovery_support::pu
    unsigned char pu
    Detecting the number of PU objects is supported.
    Definition: hwloc.h:2224
    -
    hwloc_topology_discovery_support::numa_memory
    unsigned char numa_memory
    Detecting the amount of memory in NUMA nodes is supported.
    Definition: hwloc.h:2228
    -
    hwloc_topology_discovery_support::disallowed_pu
    unsigned char disallowed_pu
    Detecting and identifying PU objects that are not available to the current process is supported.
    Definition: hwloc.h:2230
    -
    hwloc_topology_cpubind_support
    Flags describing actual PU binding support for this topology.
    Definition: hwloc.h:2242
    -
    hwloc_topology_cpubind_support::get_proc_last_cpu_location
    unsigned char get_proc_last_cpu_location
    Definition: hwloc.h:2262
    -
    hwloc_topology_cpubind_support::set_thread_cpubind
    unsigned char set_thread_cpubind
    Definition: hwloc.h:2256
    -
    hwloc_topology_cpubind_support::set_thisthread_cpubind
    unsigned char set_thisthread_cpubind
    Definition: hwloc.h:2252
    -
    hwloc_topology_cpubind_support::get_thisthread_last_cpu_location
    unsigned char get_thisthread_last_cpu_location
    Definition: hwloc.h:2264
    -
    hwloc_topology_cpubind_support::get_thisproc_cpubind
    unsigned char get_thisproc_cpubind
    Definition: hwloc.h:2246
    -
    hwloc_topology_cpubind_support::get_thisthread_cpubind
    unsigned char get_thisthread_cpubind
    Definition: hwloc.h:2254
    -
    hwloc_topology_cpubind_support::get_thread_cpubind
    unsigned char get_thread_cpubind
    Definition: hwloc.h:2258
    -
    hwloc_topology_cpubind_support::set_thisproc_cpubind
    unsigned char set_thisproc_cpubind
    Definition: hwloc.h:2244
    -
    hwloc_topology_cpubind_support::set_proc_cpubind
    unsigned char set_proc_cpubind
    Definition: hwloc.h:2248
    -
    hwloc_topology_cpubind_support::get_proc_cpubind
    unsigned char get_proc_cpubind
    Definition: hwloc.h:2250
    -
    hwloc_topology_cpubind_support::get_thisproc_last_cpu_location
    unsigned char get_thisproc_last_cpu_location
    Definition: hwloc.h:2260
    -
    hwloc_topology_membind_support
    Flags describing actual memory binding support for this topology.
    Definition: hwloc.h:2272
    -
    hwloc_topology_membind_support::set_thisthread_membind
    unsigned char set_thisthread_membind
    Definition: hwloc.h:2282
    -
    hwloc_topology_membind_support::get_area_membind
    unsigned char get_area_membind
    Definition: hwloc.h:2288
    -
    hwloc_topology_membind_support::firsttouch_membind
    unsigned char firsttouch_membind
    Definition: hwloc.h:2292
    -
    hwloc_topology_membind_support::get_area_memlocation
    unsigned char get_area_memlocation
    Definition: hwloc.h:2302
    -
    hwloc_topology_membind_support::set_thisproc_membind
    unsigned char set_thisproc_membind
    Definition: hwloc.h:2274
    -
    hwloc_topology_membind_support::interleave_membind
    unsigned char interleave_membind
    Definition: hwloc.h:2296
    -
    hwloc_topology_membind_support::get_thisproc_membind
    unsigned char get_thisproc_membind
    Definition: hwloc.h:2276
    -
    hwloc_topology_membind_support::set_area_membind
    unsigned char set_area_membind
    Definition: hwloc.h:2286
    -
    hwloc_topology_membind_support::get_thisthread_membind
    unsigned char get_thisthread_membind
    Definition: hwloc.h:2284
    -
    hwloc_topology_membind_support::set_proc_membind
    unsigned char set_proc_membind
    Definition: hwloc.h:2278
    -
    hwloc_topology_membind_support::get_proc_membind
    unsigned char get_proc_membind
    Definition: hwloc.h:2280
    -
    hwloc_topology_membind_support::migrate_membind
    unsigned char migrate_membind
    Definition: hwloc.h:2300
    -
    hwloc_topology_membind_support::nexttouch_membind
    unsigned char nexttouch_membind
    Definition: hwloc.h:2298
    -
    hwloc_topology_membind_support::alloc_membind
    unsigned char alloc_membind
    Definition: hwloc.h:2290
    -
    hwloc_topology_membind_support::bind_membind
    unsigned char bind_membind
    Definition: hwloc.h:2294
    -
    hwloc_topology_misc_support
    Flags describing miscellaneous features.
    Definition: hwloc.h:2307
    -
    hwloc_topology_misc_support::imported_support
    unsigned char imported_support
    Definition: hwloc.h:2309
    -
    hwloc_topology_support
    Set of flags describing actual support for this topology.
    Definition: hwloc.h:2318
    -
    hwloc_topology_support::misc
    struct hwloc_topology_misc_support * misc
    Definition: hwloc.h:2322
    -
    hwloc_topology_support::membind
    struct hwloc_topology_membind_support * membind
    Definition: hwloc.h:2321
    -
    hwloc_topology_support::cpubind
    struct hwloc_topology_cpubind_support * cpubind
    Definition: hwloc.h:2320
    -
    hwloc_topology_support::discovery
    struct hwloc_topology_discovery_support * discovery
    Definition: hwloc.h:2319
    -
    - - - - - - - - -
    -
    helper.h
    -
    -
    -
    1/*
    -
    2 * Copyright © 2009 CNRS
    -
    3 * Copyright © 2009-2023 Inria. All rights reserved.
    -
    4 * Copyright © 2009-2012 Université Bordeaux
    -
    5 * Copyright © 2009-2010 Cisco Systems, Inc. All rights reserved.
    -
    6 * See COPYING in top-level directory.
    -
    7 */
    -
    8
    -
    13#ifndef HWLOC_HELPER_H
    -
    14#define HWLOC_HELPER_H
    -
    15
    -
    16#ifndef HWLOC_H
    -
    17#error Please include the main hwloc.h instead
    -
    18#endif
    -
    19
    -
    20#include <stdlib.h>
    -
    21#include <errno.h>
    -
    22
    -
    23
    -
    24#ifdef __cplusplus
    -
    25extern "C" {
    -
    26#endif
    -
    27
    -
    28
    -
    42static __hwloc_inline hwloc_obj_t
    -
    43hwloc_get_first_largest_obj_inside_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t set)
    -
    44{
    -
    45 hwloc_obj_t obj = hwloc_get_root_obj(topology);
    -
    46 if (!hwloc_bitmap_intersects(obj->cpuset, set))
    -
    47 return NULL;
    -
    48 while (!hwloc_bitmap_isincluded(obj->cpuset, set)) {
    -
    49 /* while the object intersects without being included, look at its children */
    -
    50 hwloc_obj_t child = obj->first_child;
    -
    51 while (child) {
    -
    52 if (hwloc_bitmap_intersects(child->cpuset, set))
    -
    53 break;
    -
    54 child = child->next_sibling;
    -
    55 }
    -
    56 if (!child)
    -
    57 /* no child intersects, return their father */
    -
    58 return obj;
    -
    59 /* found one intersecting child, look at its children */
    -
    60 obj = child;
    -
    61 }
    -
    62 /* obj is included, return it */
    -
    63 return obj;
    -
    64}
    -
    65
    -
    71HWLOC_DECLSPEC int hwloc_get_largest_objs_inside_cpuset (hwloc_topology_t topology, hwloc_const_cpuset_t set,
    -
    72 hwloc_obj_t * __hwloc_restrict objs, int max);
    -
    73
    -
    89static __hwloc_inline hwloc_obj_t
    -
    90hwloc_get_next_obj_inside_cpuset_by_depth (hwloc_topology_t topology, hwloc_const_cpuset_t set,
    -
    91 int depth, hwloc_obj_t prev)
    -
    92{
    -
    93 hwloc_obj_t next = hwloc_get_next_obj_by_depth(topology, depth, prev);
    -
    94 if (!next)
    -
    95 return NULL;
    -
    96 while (next && (hwloc_bitmap_iszero(next->cpuset) || !hwloc_bitmap_isincluded(next->cpuset, set)))
    -
    97 next = next->next_cousin;
    -
    98 return next;
    -
    99}
    -
    100
    -
    119static __hwloc_inline hwloc_obj_t
    -
    120hwloc_get_next_obj_inside_cpuset_by_type (hwloc_topology_t topology, hwloc_const_cpuset_t set,
    -
    121 hwloc_obj_type_t type, hwloc_obj_t prev)
    -
    122{
    -
    123 int depth = hwloc_get_type_depth(topology, type);
    -
    124 if (depth == HWLOC_TYPE_DEPTH_UNKNOWN || depth == HWLOC_TYPE_DEPTH_MULTIPLE)
    -
    125 return NULL;
    -
    126 return hwloc_get_next_obj_inside_cpuset_by_depth(topology, set, depth, prev);
    -
    127}
    -
    128
    -
    139static __hwloc_inline hwloc_obj_t
    -
    140hwloc_get_obj_inside_cpuset_by_depth (hwloc_topology_t topology, hwloc_const_cpuset_t set,
    -
    141 int depth, unsigned idx) __hwloc_attribute_pure;
    -
    142static __hwloc_inline hwloc_obj_t
    -
    143hwloc_get_obj_inside_cpuset_by_depth (hwloc_topology_t topology, hwloc_const_cpuset_t set,
    -
    144 int depth, unsigned idx)
    -
    145{
    -
    146 hwloc_obj_t obj = hwloc_get_obj_by_depth (topology, depth, 0);
    -
    147 unsigned count = 0;
    -
    148 if (!obj)
    -
    149 return NULL;
    -
    150 while (obj) {
    -
    151 if (!hwloc_bitmap_iszero(obj->cpuset) && hwloc_bitmap_isincluded(obj->cpuset, set)) {
    -
    152 if (count == idx)
    -
    153 return obj;
    -
    154 count++;
    -
    155 }
    -
    156 obj = obj->next_cousin;
    -
    157 }
    -
    158 return NULL;
    -
    159}
    -
    160
    -
    175static __hwloc_inline hwloc_obj_t
    -
    176hwloc_get_obj_inside_cpuset_by_type (hwloc_topology_t topology, hwloc_const_cpuset_t set,
    -
    177 hwloc_obj_type_t type, unsigned idx) __hwloc_attribute_pure;
    -
    178static __hwloc_inline hwloc_obj_t
    -
    179hwloc_get_obj_inside_cpuset_by_type (hwloc_topology_t topology, hwloc_const_cpuset_t set,
    -
    180 hwloc_obj_type_t type, unsigned idx)
    -
    181{
    -
    182 int depth = hwloc_get_type_depth(topology, type);
    -
    183 if (depth == HWLOC_TYPE_DEPTH_UNKNOWN || depth == HWLOC_TYPE_DEPTH_MULTIPLE)
    -
    184 return NULL;
    -
    185 return hwloc_get_obj_inside_cpuset_by_depth(topology, set, depth, idx);
    -
    186}
    -
    187
    -
    199static __hwloc_inline unsigned
    -
    200hwloc_get_nbobjs_inside_cpuset_by_depth (hwloc_topology_t topology, hwloc_const_cpuset_t set,
    -
    201 int depth) __hwloc_attribute_pure;
    -
    202static __hwloc_inline unsigned
    -
    203hwloc_get_nbobjs_inside_cpuset_by_depth (hwloc_topology_t topology, hwloc_const_cpuset_t set,
    -
    204 int depth)
    -
    205{
    -
    206 hwloc_obj_t obj = hwloc_get_obj_by_depth (topology, depth, 0);
    -
    207 unsigned count = 0;
    -
    208 if (!obj)
    -
    209 return 0;
    -
    210 while (obj) {
    -
    211 if (!hwloc_bitmap_iszero(obj->cpuset) && hwloc_bitmap_isincluded(obj->cpuset, set))
    -
    212 count++;
    -
    213 obj = obj->next_cousin;
    -
    214 }
    -
    215 return count;
    -
    216}
    -
    217
    -
    231static __hwloc_inline int
    -
    232hwloc_get_nbobjs_inside_cpuset_by_type (hwloc_topology_t topology, hwloc_const_cpuset_t set,
    -
    233 hwloc_obj_type_t type) __hwloc_attribute_pure;
    -
    234static __hwloc_inline int
    -
    235hwloc_get_nbobjs_inside_cpuset_by_type (hwloc_topology_t topology, hwloc_const_cpuset_t set,
    -
    236 hwloc_obj_type_t type)
    -
    237{
    -
    238 int depth = hwloc_get_type_depth(topology, type);
    -
    239 if (depth == HWLOC_TYPE_DEPTH_UNKNOWN)
    -
    240 return 0;
    -
    241 if (depth == HWLOC_TYPE_DEPTH_MULTIPLE)
    -
    242 return -1; /* FIXME: agregate nbobjs from different levels? */
    -
    243 return (int) hwloc_get_nbobjs_inside_cpuset_by_depth(topology, set, depth);
    -
    244}
    -
    245
    -
    262static __hwloc_inline int
    -
    263hwloc_get_obj_index_inside_cpuset (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_const_cpuset_t set,
    -
    264 hwloc_obj_t obj) __hwloc_attribute_pure;
    -
    265static __hwloc_inline int
    -
    266hwloc_get_obj_index_inside_cpuset (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_const_cpuset_t set,
    -
    267 hwloc_obj_t obj)
    -
    268{
    -
    269 int idx = 0;
    -
    270 if (!hwloc_bitmap_isincluded(obj->cpuset, set))
    -
    271 return -1;
    -
    272 /* count how many objects are inside the cpuset on the way from us to the beginning of the level */
    -
    273 while ((obj = obj->prev_cousin) != NULL)
    -
    274 if (!hwloc_bitmap_iszero(obj->cpuset) && hwloc_bitmap_isincluded(obj->cpuset, set))
    -
    275 idx++;
    -
    276 return idx;
    -
    277}
    -
    278
    -
    294static __hwloc_inline hwloc_obj_t
    -
    295hwloc_get_child_covering_cpuset (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_const_cpuset_t set,
    -
    296 hwloc_obj_t parent) __hwloc_attribute_pure;
    -
    297static __hwloc_inline hwloc_obj_t
    -
    298hwloc_get_child_covering_cpuset (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_const_cpuset_t set,
    -
    299 hwloc_obj_t parent)
    -
    300{
    -
    301 hwloc_obj_t child;
    -
    302 if (hwloc_bitmap_iszero(set))
    -
    303 return NULL;
    -
    304 child = parent->first_child;
    -
    305 while (child) {
    -
    306 if (child->cpuset && hwloc_bitmap_isincluded(set, child->cpuset))
    -
    307 return child;
    -
    308 child = child->next_sibling;
    -
    309 }
    -
    310 return NULL;
    -
    311}
    -
    312
    -
    318static __hwloc_inline hwloc_obj_t
    -
    319hwloc_get_obj_covering_cpuset (hwloc_topology_t topology, hwloc_const_cpuset_t set) __hwloc_attribute_pure;
    -
    320static __hwloc_inline hwloc_obj_t
    -
    321hwloc_get_obj_covering_cpuset (hwloc_topology_t topology, hwloc_const_cpuset_t set)
    -
    322{
    -
    323 struct hwloc_obj *current = hwloc_get_root_obj(topology);
    -
    324 if (hwloc_bitmap_iszero(set) || !hwloc_bitmap_isincluded(set, current->cpuset))
    -
    325 return NULL;
    -
    326 while (1) {
    -
    327 hwloc_obj_t child = hwloc_get_child_covering_cpuset(topology, set, current);
    -
    328 if (!child)
    -
    329 return current;
    -
    330 current = child;
    -
    331 }
    -
    332}
    -
    333
    -
    347static __hwloc_inline hwloc_obj_t
    -
    348hwloc_get_next_obj_covering_cpuset_by_depth(hwloc_topology_t topology, hwloc_const_cpuset_t set,
    -
    349 int depth, hwloc_obj_t prev)
    -
    350{
    -
    351 hwloc_obj_t next = hwloc_get_next_obj_by_depth(topology, depth, prev);
    -
    352 if (!next)
    -
    353 return NULL;
    -
    354 while (next && !hwloc_bitmap_intersects(set, next->cpuset))
    -
    355 next = next->next_cousin;
    -
    356 return next;
    -
    357}
    -
    358
    -
    375static __hwloc_inline hwloc_obj_t
    -
    376hwloc_get_next_obj_covering_cpuset_by_type(hwloc_topology_t topology, hwloc_const_cpuset_t set,
    -
    377 hwloc_obj_type_t type, hwloc_obj_t prev)
    -
    378{
    -
    379 int depth = hwloc_get_type_depth(topology, type);
    -
    380 if (depth == HWLOC_TYPE_DEPTH_UNKNOWN || depth == HWLOC_TYPE_DEPTH_MULTIPLE)
    -
    381 return NULL;
    -
    382 return hwloc_get_next_obj_covering_cpuset_by_depth(topology, set, depth, prev);
    -
    383}
    -
    384
    -
    408static __hwloc_inline hwloc_obj_t
    -
    409hwloc_get_ancestor_obj_by_depth (hwloc_topology_t topology __hwloc_attribute_unused, int depth, hwloc_obj_t obj) __hwloc_attribute_pure;
    -
    410static __hwloc_inline hwloc_obj_t
    -
    411hwloc_get_ancestor_obj_by_depth (hwloc_topology_t topology __hwloc_attribute_unused, int depth, hwloc_obj_t obj)
    -
    412{
    -
    413 hwloc_obj_t ancestor = obj;
    -
    414 if (obj->depth < depth)
    -
    415 return NULL;
    -
    416 while (ancestor && ancestor->depth > depth)
    -
    417 ancestor = ancestor->parent;
    -
    418 return ancestor;
    -
    419}
    -
    420
    -
    434static __hwloc_inline hwloc_obj_t
    -
    435hwloc_get_ancestor_obj_by_type (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_obj_type_t type, hwloc_obj_t obj) __hwloc_attribute_pure;
    -
    436static __hwloc_inline hwloc_obj_t
    -
    437hwloc_get_ancestor_obj_by_type (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_obj_type_t type, hwloc_obj_t obj)
    -
    438{
    -
    439 hwloc_obj_t ancestor = obj->parent;
    -
    440 while (ancestor && ancestor->type != type)
    -
    441 ancestor = ancestor->parent;
    -
    442 return ancestor;
    -
    443}
    -
    444
    -
    451static __hwloc_inline hwloc_obj_t
    -
    452hwloc_get_common_ancestor_obj (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_obj_t obj1, hwloc_obj_t obj2) __hwloc_attribute_pure;
    -
    453static __hwloc_inline hwloc_obj_t
    -
    454hwloc_get_common_ancestor_obj (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_obj_t obj1, hwloc_obj_t obj2)
    -
    455{
    -
    456 /* the loop isn't so easy since intermediate ancestors may have
    -
    457 * different depth, causing us to alternate between using obj1->parent
    -
    458 * and obj2->parent. Also, even if at some point we find ancestors of
    -
    459 * of the same depth, their ancestors may have different depth again.
    -
    460 */
    -
    461 while (obj1 != obj2) {
    -
    462 while (obj1->depth > obj2->depth)
    -
    463 obj1 = obj1->parent;
    -
    464 while (obj2->depth > obj1->depth)
    -
    465 obj2 = obj2->parent;
    -
    466 if (obj1 != obj2 && obj1->depth == obj2->depth) {
    -
    467 obj1 = obj1->parent;
    -
    468 obj2 = obj2->parent;
    -
    469 }
    -
    470 }
    -
    471 return obj1;
    -
    472}
    -
    473
    -
    481static __hwloc_inline int
    -
    482hwloc_obj_is_in_subtree (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_obj_t obj, hwloc_obj_t subtree_root) __hwloc_attribute_pure;
    -
    483static __hwloc_inline int
    -
    484hwloc_obj_is_in_subtree (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_obj_t obj, hwloc_obj_t subtree_root)
    -
    485{
    -
    486 return obj->cpuset && subtree_root->cpuset && hwloc_bitmap_isincluded(obj->cpuset, subtree_root->cpuset);
    -
    487}
    -
    488
    -
    499static __hwloc_inline hwloc_obj_t
    -
    500hwloc_get_next_child (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_obj_t parent, hwloc_obj_t prev)
    -
    501{
    -
    502 hwloc_obj_t obj;
    -
    503 int state = 0;
    -
    504 if (prev) {
    -
    505 if (prev->type == HWLOC_OBJ_MISC)
    -
    506 state = 3;
    -
    507 else if (prev->type == HWLOC_OBJ_BRIDGE || prev->type == HWLOC_OBJ_PCI_DEVICE || prev->type == HWLOC_OBJ_OS_DEVICE)
    -
    508 state = 2;
    -
    509 else if (prev->type == HWLOC_OBJ_NUMANODE)
    -
    510 state = 1;
    -
    511 obj = prev->next_sibling;
    -
    512 } else {
    -
    513 obj = parent->first_child;
    -
    514 }
    -
    515 if (!obj && state == 0) {
    -
    516 obj = parent->memory_first_child;
    -
    517 state = 1;
    -
    518 }
    -
    519 if (!obj && state == 1) {
    -
    520 obj = parent->io_first_child;
    -
    521 state = 2;
    -
    522 }
    -
    523 if (!obj && state == 2) {
    -
    524 obj = parent->misc_first_child;
    -
    525 state = 3;
    -
    526 }
    -
    527 return obj;
    -
    528}
    -
    529
    -
    556HWLOC_DECLSPEC int
    -
    557hwloc_obj_type_is_normal(hwloc_obj_type_t type);
    -
    558
    -
    567HWLOC_DECLSPEC int
    -
    568hwloc_obj_type_is_io(hwloc_obj_type_t type);
    -
    569
    -
    578HWLOC_DECLSPEC int
    -
    579hwloc_obj_type_is_memory(hwloc_obj_type_t type);
    -
    580
    -
    587HWLOC_DECLSPEC int
    -
    588hwloc_obj_type_is_cache(hwloc_obj_type_t type);
    -
    589
    -
    596HWLOC_DECLSPEC int
    -
    597hwloc_obj_type_is_dcache(hwloc_obj_type_t type);
    -
    598
    -
    605HWLOC_DECLSPEC int
    -
    606hwloc_obj_type_is_icache(hwloc_obj_type_t type);
    -
    607
    -
    639static __hwloc_inline int
    -
    640hwloc_get_cache_type_depth (hwloc_topology_t topology,
    -
    641 unsigned cachelevel, hwloc_obj_cache_type_t cachetype)
    -
    642{
    -
    643 int depth;
    -
    644 int found = HWLOC_TYPE_DEPTH_UNKNOWN;
    -
    645 for (depth=0; ; depth++) {
    -
    646 hwloc_obj_t obj = hwloc_get_obj_by_depth(topology, depth, 0);
    -
    647 if (!obj)
    -
    648 break;
    -
    649 if (!hwloc_obj_type_is_dcache(obj->type) || obj->attr->cache.depth != cachelevel)
    -
    650 /* doesn't match, try next depth */
    -
    651 continue;
    -
    652 if (cachetype == (hwloc_obj_cache_type_t) -1) {
    -
    653 if (found != HWLOC_TYPE_DEPTH_UNKNOWN) {
    -
    654 /* second match, return MULTIPLE */
    -
    655 return HWLOC_TYPE_DEPTH_MULTIPLE;
    -
    656 }
    -
    657 /* first match, mark it as found */
    -
    658 found = depth;
    -
    659 continue;
    -
    660 }
    -
    661 if (obj->attr->cache.type == cachetype || obj->attr->cache.type == HWLOC_OBJ_CACHE_UNIFIED)
    -
    662 /* exact match (either unified is alone, or we match instruction or data), return immediately */
    -
    663 return depth;
    -
    664 }
    -
    665 /* went to the bottom, return what we found */
    -
    666 return found;
    -
    667}
    -
    668
    -
    673static __hwloc_inline hwloc_obj_t
    -
    674hwloc_get_cache_covering_cpuset (hwloc_topology_t topology, hwloc_const_cpuset_t set) __hwloc_attribute_pure;
    -
    675static __hwloc_inline hwloc_obj_t
    -
    676hwloc_get_cache_covering_cpuset (hwloc_topology_t topology, hwloc_const_cpuset_t set)
    -
    677{
    -
    678 hwloc_obj_t current = hwloc_get_obj_covering_cpuset(topology, set);
    -
    679 while (current) {
    -
    680 if (hwloc_obj_type_is_dcache(current->type))
    -
    681 return current;
    -
    682 current = current->parent;
    -
    683 }
    -
    684 return NULL;
    -
    685}
    -
    686
    -
    692static __hwloc_inline hwloc_obj_t
    -
    693hwloc_get_shared_cache_covering_obj (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_obj_t obj) __hwloc_attribute_pure;
    -
    694static __hwloc_inline hwloc_obj_t
    -
    695hwloc_get_shared_cache_covering_obj (hwloc_topology_t topology __hwloc_attribute_unused, hwloc_obj_t obj)
    -
    696{
    -
    697 hwloc_obj_t current = obj->parent;
    -
    698 if (!obj->cpuset)
    -
    699 return NULL;
    -
    700 while (current) {
    -
    701 if (!hwloc_bitmap_isequal(current->cpuset, obj->cpuset)
    -
    702 && hwloc_obj_type_is_dcache(current->type))
    -
    703 return current;
    -
    704 current = current->parent;
    -
    705 }
    -
    706 return NULL;
    -
    707}
    -
    708
    -
    740HWLOC_DECLSPEC int hwloc_bitmap_singlify_per_core(hwloc_topology_t topology, hwloc_bitmap_t cpuset, unsigned which);
    -
    741
    -
    753static __hwloc_inline hwloc_obj_t
    -
    754hwloc_get_pu_obj_by_os_index(hwloc_topology_t topology, unsigned os_index) __hwloc_attribute_pure;
    -
    755static __hwloc_inline hwloc_obj_t
    -
    756hwloc_get_pu_obj_by_os_index(hwloc_topology_t topology, unsigned os_index)
    -
    757{
    -
    758 hwloc_obj_t obj = NULL;
    -
    759 while ((obj = hwloc_get_next_obj_by_type(topology, HWLOC_OBJ_PU, obj)) != NULL)
    -
    760 if (obj->os_index == os_index)
    -
    761 return obj;
    -
    762 return NULL;
    -
    763}
    -
    764
    -
    776static __hwloc_inline hwloc_obj_t
    -
    777hwloc_get_numanode_obj_by_os_index(hwloc_topology_t topology, unsigned os_index) __hwloc_attribute_pure;
    -
    778static __hwloc_inline hwloc_obj_t
    -
    779hwloc_get_numanode_obj_by_os_index(hwloc_topology_t topology, unsigned os_index)
    -
    780{
    -
    781 hwloc_obj_t obj = NULL;
    -
    782 while ((obj = hwloc_get_next_obj_by_type(topology, HWLOC_OBJ_NUMANODE, obj)) != NULL)
    -
    783 if (obj->os_index == os_index)
    -
    784 return obj;
    -
    785 return NULL;
    -
    786}
    -
    787
    -
    799/* TODO: rather provide an iterator? Provide a way to know how much should be allocated? By returning the total number of objects instead? */
    -
    800HWLOC_DECLSPEC unsigned hwloc_get_closest_objs (hwloc_topology_t topology, hwloc_obj_t src, hwloc_obj_t * __hwloc_restrict objs, unsigned max);
    -
    801
    -
    816static __hwloc_inline hwloc_obj_t
    -
    817hwloc_get_obj_below_by_type (hwloc_topology_t topology,
    -
    818 hwloc_obj_type_t type1, unsigned idx1,
    -
    819 hwloc_obj_type_t type2, unsigned idx2) __hwloc_attribute_pure;
    -
    820static __hwloc_inline hwloc_obj_t
    -
    821hwloc_get_obj_below_by_type (hwloc_topology_t topology,
    -
    822 hwloc_obj_type_t type1, unsigned idx1,
    -
    823 hwloc_obj_type_t type2, unsigned idx2)
    -
    824{
    -
    825 hwloc_obj_t obj;
    -
    826 obj = hwloc_get_obj_by_type (topology, type1, idx1);
    -
    827 if (!obj)
    -
    828 return NULL;
    -
    829 return hwloc_get_obj_inside_cpuset_by_type(topology, obj->cpuset, type2, idx2);
    -
    830}
    -
    831
    -
    852static __hwloc_inline hwloc_obj_t
    -
    853hwloc_get_obj_below_array_by_type (hwloc_topology_t topology, int nr, hwloc_obj_type_t *typev, unsigned *idxv) __hwloc_attribute_pure;
    -
    854static __hwloc_inline hwloc_obj_t
    -
    855hwloc_get_obj_below_array_by_type (hwloc_topology_t topology, int nr, hwloc_obj_type_t *typev, unsigned *idxv)
    -
    856{
    -
    857 hwloc_obj_t obj = hwloc_get_root_obj(topology);
    -
    858 int i;
    -
    859 for(i=0; i<nr; i++) {
    -
    860 if (!obj)
    -
    861 return NULL;
    -
    862 obj = hwloc_get_obj_inside_cpuset_by_type(topology, obj->cpuset, typev[i], idxv[i]);
    -
    863 }
    -
    864 return obj;
    -
    865}
    -
    866
    -
    905HWLOC_DECLSPEC hwloc_obj_t
    -
    906hwloc_get_obj_with_same_locality(hwloc_topology_t topology, hwloc_obj_t src,
    -
    907 hwloc_obj_type_t type, const char *subtype, const char *nameprefix,
    -
    908 unsigned long flags);
    -
    909
    -
    920enum hwloc_distrib_flags_e {
    -
    924 HWLOC_DISTRIB_FLAG_REVERSE = (1UL<<0)
    -
    925};
    -
    926
    -
    949static __hwloc_inline int
    -
    950hwloc_distrib(hwloc_topology_t topology,
    -
    951 hwloc_obj_t *roots, unsigned n_roots,
    -
    952 hwloc_cpuset_t *set,
    -
    953 unsigned n,
    -
    954 int until, unsigned long flags)
    -
    955{
    -
    956 unsigned i;
    -
    957 unsigned tot_weight;
    -
    958 unsigned given, givenweight;
    -
    959 hwloc_cpuset_t *cpusetp = set;
    -
    960
    -
    961 if (flags & ~HWLOC_DISTRIB_FLAG_REVERSE) {
    -
    962 errno = EINVAL;
    -
    963 return -1;
    -
    964 }
    -
    965
    -
    966 tot_weight = 0;
    -
    967 for (i = 0; i < n_roots; i++)
    -
    968 tot_weight += (unsigned) hwloc_bitmap_weight(roots[i]->cpuset);
    -
    969
    -
    970 for (i = 0, given = 0, givenweight = 0; i < n_roots; i++) {
    -
    971 unsigned chunk, weight;
    -
    972 hwloc_obj_t root = roots[flags & HWLOC_DISTRIB_FLAG_REVERSE ? n_roots-1-i : i];
    -
    973 hwloc_cpuset_t cpuset = root->cpuset;
    -
    974 while (!hwloc_obj_type_is_normal(root->type))
    -
    975 /* If memory/io/misc, walk up to normal parent */
    -
    976 root = root->parent;
    -
    977 weight = (unsigned) hwloc_bitmap_weight(cpuset);
    -
    978 if (!weight)
    -
    979 continue;
    -
    980 /* Give to root a chunk proportional to its weight.
    -
    981 * If previous chunks got rounded-up, we may get a bit less. */
    -
    982 chunk = (( (givenweight+weight) * n + tot_weight-1) / tot_weight)
    -
    983 - (( givenweight * n + tot_weight-1) / tot_weight);
    -
    984 if (!root->arity || chunk <= 1 || root->depth >= until) {
    -
    985 /* We can't split any more, put everything there. */
    -
    986 if (chunk) {
    -
    987 /* Fill cpusets with ours */
    -
    988 unsigned j;
    -
    989 for (j=0; j < chunk; j++)
    -
    990 cpusetp[j] = hwloc_bitmap_dup(cpuset);
    -
    991 } else {
    -
    992 /* We got no chunk, just merge our cpuset to a previous one
    -
    993 * (the first chunk cannot be empty)
    -
    994 * so that this root doesn't get ignored.
    -
    995 */
    -
    996 assert(given);
    -
    997 hwloc_bitmap_or(cpusetp[-1], cpusetp[-1], cpuset);
    -
    998 }
    -
    999 } else {
    -
    1000 /* Still more to distribute, recurse into children */
    -
    1001 hwloc_distrib(topology, root->children, root->arity, cpusetp, chunk, until, flags);
    -
    1002 }
    -
    1003 cpusetp += chunk;
    -
    1004 given += chunk;
    -
    1005 givenweight += weight;
    -
    1006 }
    -
    1007
    -
    1008 return 0;
    -
    1009}
    -
    1010
    -
    1030HWLOC_DECLSPEC hwloc_const_cpuset_t
    -
    1031hwloc_topology_get_complete_cpuset(hwloc_topology_t topology) __hwloc_attribute_pure;
    -
    1032
    -
    1046HWLOC_DECLSPEC hwloc_const_cpuset_t
    -
    1047hwloc_topology_get_topology_cpuset(hwloc_topology_t topology) __hwloc_attribute_pure;
    -
    1048
    -
    1067HWLOC_DECLSPEC hwloc_const_cpuset_t
    -
    1068hwloc_topology_get_allowed_cpuset(hwloc_topology_t topology) __hwloc_attribute_pure;
    -
    1069
    -
    1081HWLOC_DECLSPEC hwloc_const_nodeset_t
    -
    1082hwloc_topology_get_complete_nodeset(hwloc_topology_t topology) __hwloc_attribute_pure;
    -
    1083
    -
    1097HWLOC_DECLSPEC hwloc_const_nodeset_t
    -
    1098hwloc_topology_get_topology_nodeset(hwloc_topology_t topology) __hwloc_attribute_pure;
    -
    1099
    -
    1118HWLOC_DECLSPEC hwloc_const_nodeset_t
    -
    1119hwloc_topology_get_allowed_nodeset(hwloc_topology_t topology) __hwloc_attribute_pure;
    -
    1120
    -
    1144static __hwloc_inline int
    -
    1145hwloc_cpuset_to_nodeset(hwloc_topology_t topology, hwloc_const_cpuset_t _cpuset, hwloc_nodeset_t nodeset)
    -
    1146{
    -
    1147 int depth = hwloc_get_type_depth(topology, HWLOC_OBJ_NUMANODE);
    -
    1148 hwloc_obj_t obj = NULL;
    -
    1149 assert(depth != HWLOC_TYPE_DEPTH_UNKNOWN);
    -
    1150 hwloc_bitmap_zero(nodeset);
    -
    1151 while ((obj = hwloc_get_next_obj_covering_cpuset_by_depth(topology, _cpuset, depth, obj)) != NULL)
    -
    1152 if (hwloc_bitmap_set(nodeset, obj->os_index) < 0)
    -
    1153 return -1;
    -
    1154 return 0;
    -
    1155}
    -
    1156
    -
    1171static __hwloc_inline int
    -
    1172hwloc_cpuset_from_nodeset(hwloc_topology_t topology, hwloc_cpuset_t _cpuset, hwloc_const_nodeset_t nodeset)
    -
    1173{
    -
    1174 int depth = hwloc_get_type_depth(topology, HWLOC_OBJ_NUMANODE);
    -
    1175 hwloc_obj_t obj = NULL;
    -
    1176 assert(depth != HWLOC_TYPE_DEPTH_UNKNOWN);
    -
    1177 hwloc_bitmap_zero(_cpuset);
    -
    1178 while ((obj = hwloc_get_next_obj_by_depth(topology, depth, obj)) != NULL) {
    -
    1179 if (hwloc_bitmap_isset(nodeset, obj->os_index))
    -
    1180 /* no need to check obj->cpuset because objects in levels always have a cpuset */
    -
    1181 if (hwloc_bitmap_or(_cpuset, _cpuset, obj->cpuset) < 0)
    -
    1182 return -1;
    -
    1183 }
    -
    1184 return 0;
    -
    1185}
    -
    1186
    -
    1210static __hwloc_inline hwloc_obj_t
    -
    1211hwloc_get_non_io_ancestor_obj(hwloc_topology_t topology __hwloc_attribute_unused,
    -
    1212 hwloc_obj_t ioobj)
    -
    1213{
    -
    1214 hwloc_obj_t obj = ioobj;
    -
    1215 while (obj && !obj->cpuset) {
    -
    1216 obj = obj->parent;
    -
    1217 }
    -
    1218 return obj;
    -
    1219}
    -
    1220
    -
    1227static __hwloc_inline hwloc_obj_t
    -
    1228hwloc_get_next_pcidev(hwloc_topology_t topology, hwloc_obj_t prev)
    -
    1229{
    -
    1230 return hwloc_get_next_obj_by_type(topology, HWLOC_OBJ_PCI_DEVICE, prev);
    -
    1231}
    -
    1232
    -
    1238static __hwloc_inline hwloc_obj_t
    -
    1239hwloc_get_pcidev_by_busid(hwloc_topology_t topology,
    -
    1240 unsigned domain, unsigned bus, unsigned dev, unsigned func)
    -
    1241{
    -
    1242 hwloc_obj_t obj = NULL;
    -
    1243 while ((obj = hwloc_get_next_pcidev(topology, obj)) != NULL) {
    -
    1244 if (obj->attr->pcidev.domain == domain
    -
    1245 && obj->attr->pcidev.bus == bus
    -
    1246 && obj->attr->pcidev.dev == dev
    -
    1247 && obj->attr->pcidev.func == func)
    -
    1248 return obj;
    -
    1249 }
    -
    1250 return NULL;
    -
    1251}
    -
    1252
    -
    1258static __hwloc_inline hwloc_obj_t
    -
    1259hwloc_get_pcidev_by_busidstring(hwloc_topology_t topology, const char *busid)
    -
    1260{
    -
    1261 unsigned domain = 0; /* default */
    -
    1262 unsigned bus, dev, func;
    -
    1263
    -
    1264 if (sscanf(busid, "%x:%x.%x", &bus, &dev, &func) != 3
    -
    1265 && sscanf(busid, "%x:%x:%x.%x", &domain, &bus, &dev, &func) != 4) {
    -
    1266 errno = EINVAL;
    -
    1267 return NULL;
    -
    1268 }
    -
    1269
    -
    1270 return hwloc_get_pcidev_by_busid(topology, domain, bus, dev, func);
    -
    1271}
    -
    1272
    -
    1279static __hwloc_inline hwloc_obj_t
    -
    1280hwloc_get_next_osdev(hwloc_topology_t topology, hwloc_obj_t prev)
    -
    1281{
    -
    1282 return hwloc_get_next_obj_by_type(topology, HWLOC_OBJ_OS_DEVICE, prev);
    -
    1283}
    -
    1284
    -
    1291static __hwloc_inline hwloc_obj_t
    -
    1292hwloc_get_next_bridge(hwloc_topology_t topology, hwloc_obj_t prev)
    -
    1293{
    -
    1294 return hwloc_get_next_obj_by_type(topology, HWLOC_OBJ_BRIDGE, prev);
    -
    1295}
    -
    1296
    -
    1297/* \brief Checks whether a given bridge covers a given PCI bus.
    -
    1298 *
    -
    1299 * \return 1 if it covers, 0 if not.
    -
    1300 */
    -
    1301static __hwloc_inline int
    -
    1302hwloc_bridge_covers_pcibus(hwloc_obj_t bridge,
    -
    1303 unsigned domain, unsigned bus)
    -
    1304{
    -
    1305 return bridge->type == HWLOC_OBJ_BRIDGE
    -
    1306 && bridge->attr->bridge.downstream_type == HWLOC_OBJ_BRIDGE_PCI
    -
    1307 && bridge->attr->bridge.downstream.pci.domain == domain
    -
    1308 && bridge->attr->bridge.downstream.pci.secondary_bus <= bus
    -
    1309 && bridge->attr->bridge.downstream.pci.subordinate_bus >= bus;
    -
    1310}
    -
    1311
    -
    1316#ifdef __cplusplus
    -
    1317} /* extern "C" */
    -
    1318#endif
    -
    1319
    -
    1320
    -
    1321#endif /* HWLOC_HELPER_H */
    -
    hwloc_const_cpuset_t
    hwloc_const_bitmap_t hwloc_const_cpuset_t
    A non-modifiable hwloc_cpuset_t.
    Definition: hwloc.h:163
    -
    hwloc_const_nodeset_t
    hwloc_const_bitmap_t hwloc_const_nodeset_t
    A non-modifiable hwloc_nodeset_t.
    Definition: hwloc.h:181
    -
    hwloc_nodeset_t
    hwloc_bitmap_t hwloc_nodeset_t
    A node set is a bitmap whose bits are set according to NUMA memory node physical OS indexes.
    Definition: hwloc.h:178
    -
    hwloc_cpuset_t
    hwloc_bitmap_t hwloc_cpuset_t
    A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
    Definition: hwloc.h:161
    -
    hwloc_obj_cache_type_t
    enum hwloc_obj_cache_type_e hwloc_obj_cache_type_t
    Cache type.
    -
    hwloc_obj_type_t
    hwloc_obj_type_t
    Type of topology object.
    Definition: hwloc.h:197
    -
    HWLOC_OBJ_BRIDGE_PCI
    @ HWLOC_OBJ_BRIDGE_PCI
    PCI-side of a bridge.
    Definition: hwloc.h:356
    -
    HWLOC_OBJ_CACHE_UNIFIED
    @ HWLOC_OBJ_CACHE_UNIFIED
    Unified cache.
    Definition: hwloc.h:348
    -
    HWLOC_OBJ_MISC
    @ HWLOC_OBJ_MISC
    Miscellaneous objects (filtered out by default). Objects without particular meaning,...
    Definition: hwloc.h:311
    -
    HWLOC_OBJ_OS_DEVICE
    @ HWLOC_OBJ_OS_DEVICE
    Operating system device (filtered out by default).
    Definition: hwloc.h:300
    -
    HWLOC_OBJ_PCI_DEVICE
    @ HWLOC_OBJ_PCI_DEVICE
    PCI device (filtered out by default).
    Definition: hwloc.h:290
    -
    HWLOC_OBJ_BRIDGE
    @ HWLOC_OBJ_BRIDGE
    Bridge (filtered out by default). Any bridge (or PCI switch) that connects the host or an I/O bus,...
    Definition: hwloc.h:278
    -
    HWLOC_OBJ_NUMANODE
    @ HWLOC_OBJ_NUMANODE
    NUMA node. An object that contains memory that is directly and byte-accessible to the host processors...
    Definition: hwloc.h:257
    -
    HWLOC_OBJ_PU
    @ HWLOC_OBJ_PU
    Processing Unit, or (Logical) Processor. An execution unit (may share a core with some other logical ...
    Definition: hwloc.h:222
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:716
    -
    hwloc_get_root_obj
    static hwloc_obj_t hwloc_get_root_obj(hwloc_topology_t topology)
    Returns the top-object of the topology-tree.
    -
    hwloc_get_obj_by_depth
    hwloc_obj_t hwloc_get_obj_by_depth(hwloc_topology_t topology, int depth, unsigned idx)
    Returns the topology object at logical index idx from depth depth.
    -
    hwloc_get_obj_by_type
    static hwloc_obj_t hwloc_get_obj_by_type(hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx)
    Returns the topology object at logical index idx with type type.
    -
    hwloc_get_next_obj_by_type
    static hwloc_obj_t hwloc_get_next_obj_by_type(hwloc_topology_t topology, hwloc_obj_type_t type, hwloc_obj_t prev)
    Returns the next object of type type.
    -
    hwloc_get_type_depth
    int hwloc_get_type_depth(hwloc_topology_t topology, hwloc_obj_type_t type)
    Returns the depth of objects of type type.
    -
    hwloc_get_next_obj_by_depth
    static hwloc_obj_t hwloc_get_next_obj_by_depth(hwloc_topology_t topology, int depth, hwloc_obj_t prev)
    Returns the next object at depth depth.
    -
    HWLOC_TYPE_DEPTH_UNKNOWN
    @ HWLOC_TYPE_DEPTH_UNKNOWN
    No object of given type exists in the topology.
    Definition: hwloc.h:853
    -
    HWLOC_TYPE_DEPTH_MULTIPLE
    @ HWLOC_TYPE_DEPTH_MULTIPLE
    Objects of given type exist at different depth in the topology (only for Groups).
    Definition: hwloc.h:854
    -
    hwloc_get_nbobjs_inside_cpuset_by_type
    static int hwloc_get_nbobjs_inside_cpuset_by_type(hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_type_t type)
    Return the number of objects of type type included in CPU set set.
    Definition: helper.h:235
    -
    hwloc_get_obj_inside_cpuset_by_type
    static hwloc_obj_t hwloc_get_obj_inside_cpuset_by_type(hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_type_t type, unsigned idx)
    Return the idx -th object of type type included in CPU set set.
    Definition: helper.h:179
    -
    hwloc_get_largest_objs_inside_cpuset
    int hwloc_get_largest_objs_inside_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_t *restrict objs, int max)
    Get the set of largest objects covering exactly a given cpuset set.
    -
    hwloc_get_obj_index_inside_cpuset
    static int hwloc_get_obj_index_inside_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_t obj)
    Return the logical index among the objects included in CPU set set.
    Definition: helper.h:266
    -
    hwloc_get_first_largest_obj_inside_cpuset
    static hwloc_obj_t hwloc_get_first_largest_obj_inside_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t set)
    Get the first largest object included in the given cpuset set.
    Definition: helper.h:43
    -
    hwloc_get_next_obj_inside_cpuset_by_depth
    static hwloc_obj_t hwloc_get_next_obj_inside_cpuset_by_depth(hwloc_topology_t topology, hwloc_const_cpuset_t set, int depth, hwloc_obj_t prev)
    Return the next object at depth depth included in CPU set set.
    Definition: helper.h:90
    -
    hwloc_get_nbobjs_inside_cpuset_by_depth
    static unsigned hwloc_get_nbobjs_inside_cpuset_by_depth(hwloc_topology_t topology, hwloc_const_cpuset_t set, int depth)
    Return the number of objects at depth depth included in CPU set set.
    Definition: helper.h:203
    -
    hwloc_get_obj_inside_cpuset_by_depth
    static hwloc_obj_t hwloc_get_obj_inside_cpuset_by_depth(hwloc_topology_t topology, hwloc_const_cpuset_t set, int depth, unsigned idx)
    Return the (logically) idx -th object at depth depth included in CPU set set.
    Definition: helper.h:143
    -
    hwloc_get_next_obj_inside_cpuset_by_type
    static hwloc_obj_t hwloc_get_next_obj_inside_cpuset_by_type(hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_type_t type, hwloc_obj_t prev)
    Return the next object of type type included in CPU set set.
    Definition: helper.h:120
    -
    hwloc_get_child_covering_cpuset
    static hwloc_obj_t hwloc_get_child_covering_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_t parent)
    Get the child covering at least CPU set set.
    Definition: helper.h:298
    -
    hwloc_get_obj_covering_cpuset
    static hwloc_obj_t hwloc_get_obj_covering_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t set)
    Get the lowest object covering at least CPU set set.
    Definition: helper.h:321
    -
    hwloc_get_next_obj_covering_cpuset_by_type
    static hwloc_obj_t hwloc_get_next_obj_covering_cpuset_by_type(hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_type_t type, hwloc_obj_t prev)
    Iterate through same-type objects covering at least CPU set set.
    Definition: helper.h:376
    -
    hwloc_get_next_obj_covering_cpuset_by_depth
    static hwloc_obj_t hwloc_get_next_obj_covering_cpuset_by_depth(hwloc_topology_t topology, hwloc_const_cpuset_t set, int depth, hwloc_obj_t prev)
    Iterate through same-depth objects covering at least CPU set set.
    Definition: helper.h:348
    -
    hwloc_get_next_child
    static hwloc_obj_t hwloc_get_next_child(hwloc_topology_t topology, hwloc_obj_t parent, hwloc_obj_t prev)
    Return the next child.
    Definition: helper.h:500
    -
    hwloc_obj_is_in_subtree
    static int hwloc_obj_is_in_subtree(hwloc_topology_t topology, hwloc_obj_t obj, hwloc_obj_t subtree_root)
    Returns true if obj is inside the subtree beginning with ancestor object subtree_root.
    Definition: helper.h:484
    -
    hwloc_get_ancestor_obj_by_type
    static hwloc_obj_t hwloc_get_ancestor_obj_by_type(hwloc_topology_t topology, hwloc_obj_type_t type, hwloc_obj_t obj)
    Returns the ancestor object of obj with type type.
    Definition: helper.h:437
    -
    hwloc_get_ancestor_obj_by_depth
    static hwloc_obj_t hwloc_get_ancestor_obj_by_depth(hwloc_topology_t topology, int depth, hwloc_obj_t obj)
    Returns the ancestor object of obj at depth depth.
    Definition: helper.h:411
    -
    hwloc_get_common_ancestor_obj
    static hwloc_obj_t hwloc_get_common_ancestor_obj(hwloc_topology_t topology, hwloc_obj_t obj1, hwloc_obj_t obj2)
    Returns the common parent object to objects obj1 and obj2.
    Definition: helper.h:454
    -
    hwloc_obj_type_is_memory
    int hwloc_obj_type_is_memory(hwloc_obj_type_t type)
    Check whether an object type is Memory.
    -
    hwloc_obj_type_is_cache
    int hwloc_obj_type_is_cache(hwloc_obj_type_t type)
    Check whether an object type is a CPU Cache (Data, Unified or Instruction).
    -
    hwloc_obj_type_is_dcache
    int hwloc_obj_type_is_dcache(hwloc_obj_type_t type)
    Check whether an object type is a CPU Data or Unified Cache.
    -
    hwloc_obj_type_is_normal
    int hwloc_obj_type_is_normal(hwloc_obj_type_t type)
    Check whether an object type is Normal.
    -
    hwloc_obj_type_is_icache
    int hwloc_obj_type_is_icache(hwloc_obj_type_t type)
    Check whether an object type is a CPU Instruction Cache,.
    -
    hwloc_obj_type_is_io
    int hwloc_obj_type_is_io(hwloc_obj_type_t type)
    Check whether an object type is I/O.
    -
    hwloc_get_shared_cache_covering_obj
    static hwloc_obj_t hwloc_get_shared_cache_covering_obj(hwloc_topology_t topology, hwloc_obj_t obj)
    Get the first data (or unified) cache shared between an object and somebody else.
    Definition: helper.h:695
    -
    hwloc_get_cache_covering_cpuset
    static hwloc_obj_t hwloc_get_cache_covering_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t set)
    Get the first data (or unified) cache covering a cpuset set.
    Definition: helper.h:676
    -
    hwloc_get_cache_type_depth
    static int hwloc_get_cache_type_depth(hwloc_topology_t topology, unsigned cachelevel, hwloc_obj_cache_type_t cachetype)
    Find the depth of cache objects matching cache level and type.
    Definition: helper.h:640
    -
    hwloc_bitmap_singlify_per_core
    int hwloc_bitmap_singlify_per_core(hwloc_topology_t topology, hwloc_bitmap_t cpuset, unsigned which)
    Remove simultaneous multithreading PUs from a CPU set.
    -
    hwloc_get_closest_objs
    unsigned hwloc_get_closest_objs(hwloc_topology_t topology, hwloc_obj_t src, hwloc_obj_t *restrict objs, unsigned max)
    Do a depth-first traversal of the topology to find and sort.
    -
    hwloc_get_pu_obj_by_os_index
    static hwloc_obj_t hwloc_get_pu_obj_by_os_index(hwloc_topology_t topology, unsigned os_index)
    Returns the object of type HWLOC_OBJ_PU with os_index.
    Definition: helper.h:756
    -
    hwloc_get_obj_below_by_type
    static hwloc_obj_t hwloc_get_obj_below_by_type(hwloc_topology_t topology, hwloc_obj_type_t type1, unsigned idx1, hwloc_obj_type_t type2, unsigned idx2)
    Find an object below another object, both specified by types and indexes.
    Definition: helper.h:821
    -
    hwloc_get_obj_with_same_locality
    hwloc_obj_t hwloc_get_obj_with_same_locality(hwloc_topology_t topology, hwloc_obj_t src, hwloc_obj_type_t type, const char *subtype, const char *nameprefix, unsigned long flags)
    Return an object of a different type with same locality.
    -
    hwloc_get_numanode_obj_by_os_index
    static hwloc_obj_t hwloc_get_numanode_obj_by_os_index(hwloc_topology_t topology, unsigned os_index)
    Returns the object of type HWLOC_OBJ_NUMANODE with os_index.
    Definition: helper.h:779
    -
    hwloc_get_obj_below_array_by_type
    static hwloc_obj_t hwloc_get_obj_below_array_by_type(hwloc_topology_t topology, int nr, hwloc_obj_type_t *typev, unsigned *idxv)
    Find an object below a chain of objects specified by types and indexes.
    Definition: helper.h:855
    -
    hwloc_distrib
    static int hwloc_distrib(hwloc_topology_t topology, hwloc_obj_t *roots, unsigned n_roots, hwloc_cpuset_t *set, unsigned n, int until, unsigned long flags)
    Distribute n items over the topology under roots.
    Definition: helper.h:950
    -
    hwloc_distrib_flags_e
    hwloc_distrib_flags_e
    Flags to be given to hwloc_distrib().
    Definition: helper.h:920
    -
    HWLOC_DISTRIB_FLAG_REVERSE
    @ HWLOC_DISTRIB_FLAG_REVERSE
    Distrib in reverse order, starting from the last objects.
    Definition: helper.h:924
    -
    hwloc_topology_get_allowed_nodeset
    hwloc_const_nodeset_t hwloc_topology_get_allowed_nodeset(hwloc_topology_t topology)
    Get allowed node set.
    -
    hwloc_topology_get_topology_nodeset
    hwloc_const_nodeset_t hwloc_topology_get_topology_nodeset(hwloc_topology_t topology)
    Get topology node set.
    -
    hwloc_topology_get_allowed_cpuset
    hwloc_const_cpuset_t hwloc_topology_get_allowed_cpuset(hwloc_topology_t topology)
    Get allowed CPU set.
    -
    hwloc_topology_get_complete_nodeset
    hwloc_const_nodeset_t hwloc_topology_get_complete_nodeset(hwloc_topology_t topology)
    Get complete node set.
    -
    hwloc_topology_get_topology_cpuset
    hwloc_const_cpuset_t hwloc_topology_get_topology_cpuset(hwloc_topology_t topology)
    Get topology CPU set.
    -
    hwloc_topology_get_complete_cpuset
    hwloc_const_cpuset_t hwloc_topology_get_complete_cpuset(hwloc_topology_t topology)
    Get complete CPU set.
    -
    hwloc_cpuset_to_nodeset
    static int hwloc_cpuset_to_nodeset(hwloc_topology_t topology, hwloc_const_cpuset_t _cpuset, hwloc_nodeset_t nodeset)
    Convert a CPU set into a NUMA node set.
    Definition: helper.h:1145
    -
    hwloc_cpuset_from_nodeset
    static int hwloc_cpuset_from_nodeset(hwloc_topology_t topology, hwloc_cpuset_t _cpuset, hwloc_const_nodeset_t nodeset)
    Convert a NUMA node set into a CPU set.
    Definition: helper.h:1172
    -
    hwloc_bridge_covers_pcibus
    static int hwloc_bridge_covers_pcibus(hwloc_obj_t bridge, unsigned domain, unsigned bus)
    Definition: helper.h:1302
    -
    hwloc_get_pcidev_by_busidstring
    static hwloc_obj_t hwloc_get_pcidev_by_busidstring(hwloc_topology_t topology, const char *busid)
    Find the PCI device object matching the PCI bus id given as a string xxxx:yy:zz.t or yy:zz....
    Definition: helper.h:1259
    -
    hwloc_get_next_pcidev
    static hwloc_obj_t hwloc_get_next_pcidev(hwloc_topology_t topology, hwloc_obj_t prev)
    Get the next PCI device in the system.
    Definition: helper.h:1228
    -
    hwloc_get_next_osdev
    static hwloc_obj_t hwloc_get_next_osdev(hwloc_topology_t topology, hwloc_obj_t prev)
    Get the next OS device in the system.
    Definition: helper.h:1280
    -
    hwloc_get_next_bridge
    static hwloc_obj_t hwloc_get_next_bridge(hwloc_topology_t topology, hwloc_obj_t prev)
    Get the next bridge in the system.
    Definition: helper.h:1292
    -
    hwloc_get_pcidev_by_busid
    static hwloc_obj_t hwloc_get_pcidev_by_busid(hwloc_topology_t topology, unsigned domain, unsigned bus, unsigned dev, unsigned func)
    Find the PCI device object matching the PCI bus id given domain, bus device and function PCI bus id.
    Definition: helper.h:1239
    -
    hwloc_get_non_io_ancestor_obj
    static hwloc_obj_t hwloc_get_non_io_ancestor_obj(hwloc_topology_t topology, hwloc_obj_t ioobj)
    Get the first non-I/O ancestor object.
    Definition: helper.h:1211
    -
    hwloc_bitmap_weight
    int hwloc_bitmap_weight(hwloc_const_bitmap_t bitmap)
    Compute the "weight" of bitmap bitmap (i.e., number of indexes that are in the bitmap).
    -
    hwloc_bitmap_isincluded
    int hwloc_bitmap_isincluded(hwloc_const_bitmap_t sub_bitmap, hwloc_const_bitmap_t super_bitmap)
    Test whether bitmap sub_bitmap is part of bitmap super_bitmap.
    -
    hwloc_bitmap_set
    int hwloc_bitmap_set(hwloc_bitmap_t bitmap, unsigned id)
    Add index id in bitmap bitmap.
    -
    hwloc_bitmap_isset
    int hwloc_bitmap_isset(hwloc_const_bitmap_t bitmap, unsigned id)
    Test whether index id is part of bitmap bitmap.
    -
    hwloc_bitmap_or
    int hwloc_bitmap_or(hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
    Or bitmaps bitmap1 and bitmap2 and store the result in bitmap res.
    -
    hwloc_bitmap_isequal
    int hwloc_bitmap_isequal(hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
    Test whether bitmap bitmap1 is equal to bitmap bitmap2.
    -
    hwloc_bitmap_iszero
    int hwloc_bitmap_iszero(hwloc_const_bitmap_t bitmap)
    Test whether bitmap bitmap is empty.
    -
    hwloc_bitmap_t
    struct hwloc_bitmap_s * hwloc_bitmap_t
    Set of bits represented as an opaque pointer to an internal bitmap.
    Definition: bitmap.h:69
    -
    hwloc_bitmap_zero
    void hwloc_bitmap_zero(hwloc_bitmap_t bitmap)
    Empty the bitmap bitmap.
    -
    hwloc_bitmap_dup
    hwloc_bitmap_t hwloc_bitmap_dup(hwloc_const_bitmap_t bitmap)
    Duplicate bitmap bitmap by allocating a new bitmap and copying bitmap contents.
    -
    hwloc_bitmap_intersects
    int hwloc_bitmap_intersects(hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
    Test whether bitmaps bitmap1 and bitmap2 intersects.
    -
    hwloc_obj
    Structure of a topology object.
    Definition: hwloc.h:420
    -
    hwloc_obj::children
    struct hwloc_obj ** children
    Normal children, children[0 .. arity -1].
    Definition: hwloc.h:480
    -
    hwloc_obj::nodeset
    hwloc_nodeset_t nodeset
    NUMA nodes covered by this object or containing this object.
    Definition: hwloc.h:564
    -
    hwloc_obj::depth
    int depth
    Vertical index in the hierarchy.
    Definition: hwloc.h:443
    -
    hwloc_obj::misc_first_child
    struct hwloc_obj * misc_first_child
    First Misc child. Misc objects are listed here (misc_arity and misc_first_child) instead of in the no...
    Definition: hwloc.h:529
    -
    hwloc_obj::subtype
    char * subtype
    Subtype string to better describe the type field.
    Definition: hwloc.h:423
    -
    hwloc_obj::os_index
    unsigned os_index
    OS-provided physical index number. It is not guaranteed unique across the entire machine,...
    Definition: hwloc.h:425
    -
    hwloc_obj::cpuset
    hwloc_cpuset_t cpuset
    CPUs covered by this object.
    Definition: hwloc.h:536
    -
    hwloc_obj::next_sibling
    struct hwloc_obj * next_sibling
    Next object below the same parent (inside the same list of children).
    Definition: hwloc.h:472
    -
    hwloc_obj::next_cousin
    struct hwloc_obj * next_cousin
    Next object of same type and depth.
    Definition: hwloc.h:466
    -
    hwloc_obj::io_first_child
    struct hwloc_obj * io_first_child
    First I/O child. Bridges, PCI and OS devices are listed here (io_arity and io_first_child) instead of...
    Definition: hwloc.h:517
    -
    hwloc_obj::arity
    unsigned arity
    Number of normal children. Memory, Misc and I/O children are not listed here but rather in their dedi...
    Definition: hwloc.h:476
    -
    hwloc_obj::memory_first_child
    struct hwloc_obj * memory_first_child
    First Memory child. NUMA nodes and Memory-side caches are listed here (memory_arity and memory_first_...
    Definition: hwloc.h:499
    -
    hwloc_obj::prev_cousin
    struct hwloc_obj * prev_cousin
    Previous object of same type and depth.
    Definition: hwloc.h:467
    -
    hwloc_obj::type
    hwloc_obj_type_t type
    Type of object.
    Definition: hwloc.h:422
    -
    hwloc_obj::attr
    union hwloc_obj_attr_u * attr
    Object type-specific Attributes, may be NULL if no attribute value was found.
    Definition: hwloc.h:439
    -
    hwloc_obj::parent
    struct hwloc_obj * parent
    Parent, NULL if root (Machine object)
    Definition: hwloc.h:470
    -
    hwloc_obj::first_child
    struct hwloc_obj * first_child
    First normal child.
    Definition: hwloc.h:481
    -
    hwloc_obj_attr_u::pcidev
    struct hwloc_obj_attr_u::hwloc_pcidev_attr_s pcidev
    -
    hwloc_obj_attr_u::bridge
    struct hwloc_obj_attr_u::hwloc_bridge_attr_s bridge
    -
    hwloc_obj_attr_u::cache
    struct hwloc_obj_attr_u::hwloc_cache_attr_s cache
    -
    hwloc_obj_attr_u::hwloc_cache_attr_s::depth
    unsigned depth
    Depth of cache (e.g., L1, L2, ...etc.)
    Definition: hwloc.h:642
    -
    hwloc_obj_attr_u::hwloc_cache_attr_s::type
    hwloc_obj_cache_type_t type
    Cache type.
    Definition: hwloc.h:646
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::dev
    unsigned char dev
    Definition: hwloc.h:663
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::func
    unsigned char func
    Definition: hwloc.h:663
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::domain
    unsigned short domain
    Definition: hwloc.h:659
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::bus
    unsigned char bus
    Definition: hwloc.h:663
    -
    hwloc_obj_attr_u::hwloc_bridge_attr_s::downstream
    union hwloc_obj_attr_u::hwloc_bridge_attr_s::@1 downstream
    -
    hwloc_obj_attr_u::hwloc_bridge_attr_s::pci
    struct hwloc_pcidev_attr_s pci
    Definition: hwloc.h:672
    -
    hwloc_obj_attr_u::hwloc_bridge_attr_s::downstream_type
    hwloc_obj_bridge_type_t downstream_type
    Definition: hwloc.h:685
    -
    - - - - - - - - -
    -
    bitmap.h
    -
    -
    -
    1/*
    -
    2 * Copyright © 2009 CNRS
    -
    3 * Copyright © 2009-2023 Inria. All rights reserved.
    -
    4 * Copyright © 2009-2012 Université Bordeaux
    -
    5 * Copyright © 2009-2011 Cisco Systems, Inc. All rights reserved.
    -
    6 * See COPYING in top-level directory.
    -
    7 */
    -
    8
    -
    13#ifndef HWLOC_BITMAP_H
    -
    14#define HWLOC_BITMAP_H
    -
    15
    -
    16#include "hwloc/autogen/config.h"
    -
    17
    -
    18#include <assert.h>
    -
    19
    -
    20
    -
    21#ifdef __cplusplus
    -
    22extern "C" {
    -
    23#endif
    -
    24
    -
    25
    -
    69typedef struct hwloc_bitmap_s * hwloc_bitmap_t;
    -
    71typedef const struct hwloc_bitmap_s * hwloc_const_bitmap_t;
    -
    72
    -
    73
    -
    74/*
    -
    75 * Bitmap allocation, freeing and copying.
    -
    76 */
    -
    77
    -
    85HWLOC_DECLSPEC hwloc_bitmap_t hwloc_bitmap_alloc(void) __hwloc_attribute_malloc;
    -
    86
    -
    94HWLOC_DECLSPEC hwloc_bitmap_t hwloc_bitmap_alloc_full(void) __hwloc_attribute_malloc;
    -
    95
    -
    100HWLOC_DECLSPEC void hwloc_bitmap_free(hwloc_bitmap_t bitmap);
    -
    101
    -
    106HWLOC_DECLSPEC hwloc_bitmap_t hwloc_bitmap_dup(hwloc_const_bitmap_t bitmap) __hwloc_attribute_malloc;
    -
    107
    -
    109HWLOC_DECLSPEC int hwloc_bitmap_copy(hwloc_bitmap_t dst, hwloc_const_bitmap_t src);
    -
    110
    -
    111
    -
    112/*
    -
    113 * Bitmap/String Conversion
    -
    114 */
    -
    115
    -
    125HWLOC_DECLSPEC int hwloc_bitmap_snprintf(char * __hwloc_restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap);
    -
    126
    -
    131HWLOC_DECLSPEC int hwloc_bitmap_asprintf(char ** strp, hwloc_const_bitmap_t bitmap);
    -
    132
    -
    137HWLOC_DECLSPEC int hwloc_bitmap_sscanf(hwloc_bitmap_t bitmap, const char * __hwloc_restrict string);
    -
    138
    -
    152HWLOC_DECLSPEC int hwloc_bitmap_list_snprintf(char * __hwloc_restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap);
    -
    153
    -
    158HWLOC_DECLSPEC int hwloc_bitmap_list_asprintf(char ** strp, hwloc_const_bitmap_t bitmap);
    -
    159
    -
    164HWLOC_DECLSPEC int hwloc_bitmap_list_sscanf(hwloc_bitmap_t bitmap, const char * __hwloc_restrict string);
    -
    165
    -
    178HWLOC_DECLSPEC int hwloc_bitmap_taskset_snprintf(char * __hwloc_restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap);
    -
    179
    -
    184HWLOC_DECLSPEC int hwloc_bitmap_taskset_asprintf(char ** strp, hwloc_const_bitmap_t bitmap);
    -
    185
    -
    190HWLOC_DECLSPEC int hwloc_bitmap_taskset_sscanf(hwloc_bitmap_t bitmap, const char * __hwloc_restrict string);
    -
    191
    -
    192
    -
    193/*
    -
    194 * Building bitmaps.
    -
    195 */
    -
    196
    -
    198HWLOC_DECLSPEC void hwloc_bitmap_zero(hwloc_bitmap_t bitmap);
    -
    199
    -
    201HWLOC_DECLSPEC void hwloc_bitmap_fill(hwloc_bitmap_t bitmap);
    -
    202
    -
    204HWLOC_DECLSPEC int hwloc_bitmap_only(hwloc_bitmap_t bitmap, unsigned id);
    -
    205
    -
    207HWLOC_DECLSPEC int hwloc_bitmap_allbut(hwloc_bitmap_t bitmap, unsigned id);
    -
    208
    -
    210HWLOC_DECLSPEC int hwloc_bitmap_from_ulong(hwloc_bitmap_t bitmap, unsigned long mask);
    -
    211
    -
    213HWLOC_DECLSPEC int hwloc_bitmap_from_ith_ulong(hwloc_bitmap_t bitmap, unsigned i, unsigned long mask);
    -
    214
    -
    216HWLOC_DECLSPEC int hwloc_bitmap_from_ulongs(hwloc_bitmap_t bitmap, unsigned nr, const unsigned long *masks);
    -
    217
    -
    218
    -
    219/*
    -
    220 * Modifying bitmaps.
    -
    221 */
    -
    222
    -
    224HWLOC_DECLSPEC int hwloc_bitmap_set(hwloc_bitmap_t bitmap, unsigned id);
    -
    225
    -
    230HWLOC_DECLSPEC int hwloc_bitmap_set_range(hwloc_bitmap_t bitmap, unsigned begin, int end);
    -
    231
    -
    233HWLOC_DECLSPEC int hwloc_bitmap_set_ith_ulong(hwloc_bitmap_t bitmap, unsigned i, unsigned long mask);
    -
    234
    -
    236HWLOC_DECLSPEC int hwloc_bitmap_clr(hwloc_bitmap_t bitmap, unsigned id);
    -
    237
    -
    242HWLOC_DECLSPEC int hwloc_bitmap_clr_range(hwloc_bitmap_t bitmap, unsigned begin, int end);
    -
    243
    -
    263HWLOC_DECLSPEC int hwloc_bitmap_singlify(hwloc_bitmap_t bitmap);
    -
    264
    -
    265
    -
    266/*
    -
    267 * Consulting bitmaps.
    -
    268 */
    -
    269
    -
    271HWLOC_DECLSPEC unsigned long hwloc_bitmap_to_ulong(hwloc_const_bitmap_t bitmap) __hwloc_attribute_pure;
    -
    272
    -
    274HWLOC_DECLSPEC unsigned long hwloc_bitmap_to_ith_ulong(hwloc_const_bitmap_t bitmap, unsigned i) __hwloc_attribute_pure;
    -
    275
    -
    282HWLOC_DECLSPEC int hwloc_bitmap_to_ulongs(hwloc_const_bitmap_t bitmap, unsigned nr, unsigned long *masks);
    -
    283
    -
    298HWLOC_DECLSPEC int hwloc_bitmap_nr_ulongs(hwloc_const_bitmap_t bitmap) __hwloc_attribute_pure;
    -
    299
    -
    304HWLOC_DECLSPEC int hwloc_bitmap_isset(hwloc_const_bitmap_t bitmap, unsigned id) __hwloc_attribute_pure;
    -
    305
    -
    310HWLOC_DECLSPEC int hwloc_bitmap_iszero(hwloc_const_bitmap_t bitmap) __hwloc_attribute_pure;
    -
    311
    -
    318HWLOC_DECLSPEC int hwloc_bitmap_isfull(hwloc_const_bitmap_t bitmap) __hwloc_attribute_pure;
    -
    319
    -
    325HWLOC_DECLSPEC int hwloc_bitmap_first(hwloc_const_bitmap_t bitmap) __hwloc_attribute_pure;
    -
    326
    -
    333HWLOC_DECLSPEC int hwloc_bitmap_next(hwloc_const_bitmap_t bitmap, int prev) __hwloc_attribute_pure;
    -
    334
    -
    340HWLOC_DECLSPEC int hwloc_bitmap_last(hwloc_const_bitmap_t bitmap) __hwloc_attribute_pure;
    -
    341
    -
    348HWLOC_DECLSPEC int hwloc_bitmap_weight(hwloc_const_bitmap_t bitmap) __hwloc_attribute_pure;
    -
    349
    -
    355HWLOC_DECLSPEC int hwloc_bitmap_first_unset(hwloc_const_bitmap_t bitmap) __hwloc_attribute_pure;
    -
    356
    -
    363HWLOC_DECLSPEC int hwloc_bitmap_next_unset(hwloc_const_bitmap_t bitmap, int prev) __hwloc_attribute_pure;
    -
    364
    -
    370HWLOC_DECLSPEC int hwloc_bitmap_last_unset(hwloc_const_bitmap_t bitmap) __hwloc_attribute_pure;
    -
    371
    -
    387#define hwloc_bitmap_foreach_begin(id, bitmap) \
    -
    388do { \
    -
    389 assert(hwloc_bitmap_weight(bitmap) != -1); \
    -
    390 for (id = hwloc_bitmap_first(bitmap); \
    -
    391 (unsigned) id != (unsigned) -1; \
    -
    392 id = hwloc_bitmap_next(bitmap, id)) {
    -
    393
    -
    401#define hwloc_bitmap_foreach_end() \
    -
    402 } \
    -
    403} while (0)
    -
    404
    -
    405
    -
    406/*
    -
    407 * Combining bitmaps.
    -
    408 */
    -
    409
    -
    414HWLOC_DECLSPEC int hwloc_bitmap_or (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2);
    -
    415
    -
    420HWLOC_DECLSPEC int hwloc_bitmap_and (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2);
    -
    421
    -
    426HWLOC_DECLSPEC int hwloc_bitmap_andnot (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2);
    -
    427
    -
    432HWLOC_DECLSPEC int hwloc_bitmap_xor (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2);
    -
    433
    -
    438HWLOC_DECLSPEC int hwloc_bitmap_not (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap);
    -
    439
    -
    440
    -
    441/*
    -
    442 * Comparing bitmaps.
    -
    443 */
    -
    444
    -
    449HWLOC_DECLSPEC int hwloc_bitmap_intersects (hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2) __hwloc_attribute_pure;
    -
    450
    -
    457HWLOC_DECLSPEC int hwloc_bitmap_isincluded (hwloc_const_bitmap_t sub_bitmap, hwloc_const_bitmap_t super_bitmap) __hwloc_attribute_pure;
    -
    458
    -
    463HWLOC_DECLSPEC int hwloc_bitmap_isequal (hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2) __hwloc_attribute_pure;
    -
    464
    -
    482HWLOC_DECLSPEC int hwloc_bitmap_compare_first(hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2) __hwloc_attribute_pure;
    -
    483
    -
    501HWLOC_DECLSPEC int hwloc_bitmap_compare(hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2) __hwloc_attribute_pure;
    -
    502
    -
    506#ifdef __cplusplus
    -
    507} /* extern "C" */
    -
    508#endif
    -
    509
    -
    510
    -
    511#endif /* HWLOC_BITMAP_H */
    -
    hwloc_bitmap_weight
    int hwloc_bitmap_weight(hwloc_const_bitmap_t bitmap)
    Compute the "weight" of bitmap bitmap (i.e., number of indexes that are in the bitmap).
    -
    hwloc_bitmap_alloc_full
    hwloc_bitmap_t hwloc_bitmap_alloc_full(void)
    Allocate a new full bitmap.
    -
    hwloc_bitmap_isincluded
    int hwloc_bitmap_isincluded(hwloc_const_bitmap_t sub_bitmap, hwloc_const_bitmap_t super_bitmap)
    Test whether bitmap sub_bitmap is part of bitmap super_bitmap.
    -
    hwloc_bitmap_set
    int hwloc_bitmap_set(hwloc_bitmap_t bitmap, unsigned id)
    Add index id in bitmap bitmap.
    -
    hwloc_bitmap_sscanf
    int hwloc_bitmap_sscanf(hwloc_bitmap_t bitmap, const char *restrict string)
    Parse a bitmap string and stores it in bitmap bitmap.
    -
    hwloc_bitmap_allbut
    int hwloc_bitmap_allbut(hwloc_bitmap_t bitmap, unsigned id)
    Fill the bitmap and clear the index id.
    -
    hwloc_bitmap_fill
    void hwloc_bitmap_fill(hwloc_bitmap_t bitmap)
    Fill bitmap bitmap with all possible indexes (even if those objects don't exist or are otherwise unav...
    -
    hwloc_bitmap_asprintf
    int hwloc_bitmap_asprintf(char **strp, hwloc_const_bitmap_t bitmap)
    Stringify a bitmap into a newly allocated string.
    -
    hwloc_bitmap_only
    int hwloc_bitmap_only(hwloc_bitmap_t bitmap, unsigned id)
    Empty the bitmap bitmap and add bit id.
    -
    hwloc_bitmap_isset
    int hwloc_bitmap_isset(hwloc_const_bitmap_t bitmap, unsigned id)
    Test whether index id is part of bitmap bitmap.
    -
    hwloc_bitmap_or
    int hwloc_bitmap_or(hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
    Or bitmaps bitmap1 and bitmap2 and store the result in bitmap res.
    -
    hwloc_bitmap_compare
    int hwloc_bitmap_compare(hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
    Compare bitmaps bitmap1 and bitmap2 in lexicographic order.
    -
    hwloc_bitmap_free
    void hwloc_bitmap_free(hwloc_bitmap_t bitmap)
    Free bitmap bitmap.
    -
    hwloc_bitmap_xor
    int hwloc_bitmap_xor(hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
    Xor bitmaps bitmap1 and bitmap2 and store the result in bitmap res.
    -
    hwloc_bitmap_isequal
    int hwloc_bitmap_isequal(hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
    Test whether bitmap bitmap1 is equal to bitmap bitmap2.
    -
    hwloc_bitmap_taskset_asprintf
    int hwloc_bitmap_taskset_asprintf(char **strp, hwloc_const_bitmap_t bitmap)
    Stringify a bitmap into a newly allocated taskset-specific string.
    -
    hwloc_bitmap_list_asprintf
    int hwloc_bitmap_list_asprintf(char **strp, hwloc_const_bitmap_t bitmap)
    Stringify a bitmap into a newly allocated list string.
    -
    hwloc_bitmap_list_snprintf
    int hwloc_bitmap_list_snprintf(char *restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap)
    Stringify a bitmap in the list format.
    -
    hwloc_bitmap_last
    int hwloc_bitmap_last(hwloc_const_bitmap_t bitmap)
    Compute the last index (most significant bit) in bitmap bitmap.
    -
    hwloc_bitmap_set_ith_ulong
    int hwloc_bitmap_set_ith_ulong(hwloc_bitmap_t bitmap, unsigned i, unsigned long mask)
    Replace i -th subset of bitmap bitmap with unsigned long mask.
    -
    hwloc_bitmap_first
    int hwloc_bitmap_first(hwloc_const_bitmap_t bitmap)
    Compute the first index (least significant bit) in bitmap bitmap.
    -
    hwloc_bitmap_last_unset
    int hwloc_bitmap_last_unset(hwloc_const_bitmap_t bitmap)
    Compute the last unset index (most significant bit) in bitmap bitmap.
    -
    hwloc_bitmap_from_ith_ulong
    int hwloc_bitmap_from_ith_ulong(hwloc_bitmap_t bitmap, unsigned i, unsigned long mask)
    Setup bitmap bitmap from unsigned long mask used as i -th subset.
    -
    hwloc_bitmap_taskset_sscanf
    int hwloc_bitmap_taskset_sscanf(hwloc_bitmap_t bitmap, const char *restrict string)
    Parse a taskset-specific bitmap string and stores it in bitmap bitmap.
    -
    hwloc_bitmap_iszero
    int hwloc_bitmap_iszero(hwloc_const_bitmap_t bitmap)
    Test whether bitmap bitmap is empty.
    -
    hwloc_bitmap_taskset_snprintf
    int hwloc_bitmap_taskset_snprintf(char *restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap)
    Stringify a bitmap in the taskset-specific format.
    -
    hwloc_bitmap_isfull
    int hwloc_bitmap_isfull(hwloc_const_bitmap_t bitmap)
    Test whether bitmap bitmap is completely full.
    -
    hwloc_bitmap_and
    int hwloc_bitmap_and(hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
    And bitmaps bitmap1 and bitmap2 and store the result in bitmap res.
    -
    hwloc_bitmap_copy
    int hwloc_bitmap_copy(hwloc_bitmap_t dst, hwloc_const_bitmap_t src)
    Copy the contents of bitmap src into the already allocated bitmap dst.
    -
    hwloc_bitmap_andnot
    int hwloc_bitmap_andnot(hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
    And bitmap bitmap1 and the negation of bitmap2 and store the result in bitmap res.
    -
    hwloc_bitmap_clr_range
    int hwloc_bitmap_clr_range(hwloc_bitmap_t bitmap, unsigned begin, int end)
    Remove indexes from begin to end in bitmap bitmap.
    -
    hwloc_bitmap_not
    int hwloc_bitmap_not(hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap)
    Negate bitmap bitmap and store the result in bitmap res.
    -
    hwloc_bitmap_snprintf
    int hwloc_bitmap_snprintf(char *restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap)
    Stringify a bitmap.
    -
    hwloc_bitmap_next_unset
    int hwloc_bitmap_next_unset(hwloc_const_bitmap_t bitmap, int prev)
    Compute the next unset index in bitmap bitmap which is after index prev.
    -
    hwloc_bitmap_set_range
    int hwloc_bitmap_set_range(hwloc_bitmap_t bitmap, unsigned begin, int end)
    Add indexes from begin to end in bitmap bitmap.
    -
    hwloc_bitmap_compare_first
    int hwloc_bitmap_compare_first(hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
    Compare bitmaps bitmap1 and bitmap2 using their lowest index.
    -
    hwloc_bitmap_t
    struct hwloc_bitmap_s * hwloc_bitmap_t
    Set of bits represented as an opaque pointer to an internal bitmap.
    Definition: bitmap.h:69
    -
    hwloc_bitmap_singlify
    int hwloc_bitmap_singlify(hwloc_bitmap_t bitmap)
    Keep a single index among those set in bitmap bitmap.
    -
    hwloc_bitmap_zero
    void hwloc_bitmap_zero(hwloc_bitmap_t bitmap)
    Empty the bitmap bitmap.
    -
    hwloc_bitmap_next
    int hwloc_bitmap_next(hwloc_const_bitmap_t bitmap, int prev)
    Compute the next index in bitmap bitmap which is after index prev.
    -
    hwloc_bitmap_to_ulong
    unsigned long hwloc_bitmap_to_ulong(hwloc_const_bitmap_t bitmap)
    Convert the beginning part of bitmap bitmap into unsigned long mask.
    -
    hwloc_bitmap_from_ulongs
    int hwloc_bitmap_from_ulongs(hwloc_bitmap_t bitmap, unsigned nr, const unsigned long *masks)
    Setup bitmap bitmap from unsigned longs masks used as first nr subsets.
    -
    hwloc_bitmap_nr_ulongs
    int hwloc_bitmap_nr_ulongs(hwloc_const_bitmap_t bitmap)
    Return the number of unsigned longs required for storing bitmap bitmap entirely.
    -
    hwloc_bitmap_to_ith_ulong
    unsigned long hwloc_bitmap_to_ith_ulong(hwloc_const_bitmap_t bitmap, unsigned i)
    Convert the i -th subset of bitmap bitmap into unsigned long mask.
    -
    hwloc_bitmap_to_ulongs
    int hwloc_bitmap_to_ulongs(hwloc_const_bitmap_t bitmap, unsigned nr, unsigned long *masks)
    Convert the first nr subsets of bitmap bitmap into the array of nr unsigned long masks.
    -
    hwloc_bitmap_from_ulong
    int hwloc_bitmap_from_ulong(hwloc_bitmap_t bitmap, unsigned long mask)
    Setup bitmap bitmap from unsigned long mask.
    -
    hwloc_bitmap_alloc
    hwloc_bitmap_t hwloc_bitmap_alloc(void)
    Allocate a new empty bitmap.
    -
    hwloc_bitmap_first_unset
    int hwloc_bitmap_first_unset(hwloc_const_bitmap_t bitmap)
    Compute the first unset index (least significant bit) in bitmap bitmap.
    -
    hwloc_bitmap_dup
    hwloc_bitmap_t hwloc_bitmap_dup(hwloc_const_bitmap_t bitmap)
    Duplicate bitmap bitmap by allocating a new bitmap and copying bitmap contents.
    -
    hwloc_const_bitmap_t
    const struct hwloc_bitmap_s * hwloc_const_bitmap_t
    a non-modifiable hwloc_bitmap_t
    Definition: bitmap.h:71
    -
    hwloc_bitmap_intersects
    int hwloc_bitmap_intersects(hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
    Test whether bitmaps bitmap1 and bitmap2 intersects.
    -
    hwloc_bitmap_clr
    int hwloc_bitmap_clr(hwloc_bitmap_t bitmap, unsigned id)
    Remove index id from bitmap bitmap.
    -
    hwloc_bitmap_list_sscanf
    int hwloc_bitmap_list_sscanf(hwloc_bitmap_t bitmap, const char *restrict string)
    Parse a list string and stores it in bitmap bitmap.
    -
    - - - - - - - - -
    -
    export.h
    -
    -
    -
    1/*
    -
    2 * Copyright © 2009-2018 Inria. All rights reserved.
    -
    3 * Copyright © 2009-2012 Université Bordeaux
    -
    4 * Copyright © 2009-2011 Cisco Systems, Inc. All rights reserved.
    -
    5 * See COPYING in top-level directory.
    -
    6 */
    -
    7
    -
    12#ifndef HWLOC_EXPORT_H
    -
    13#define HWLOC_EXPORT_H
    -
    14
    -
    15#ifndef HWLOC_H
    -
    16#error Please include the main hwloc.h instead
    -
    17#endif
    -
    18
    -
    19
    -
    20#ifdef __cplusplus
    -
    21extern "C" {
    -
    22#elif 0
    -
    23}
    -
    24#endif
    -
    25
    -
    26
    -
    35enum hwloc_topology_export_xml_flags_e {
    -
    40 HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1 = (1UL<<0)
    -
    41};
    -
    42
    -
    71HWLOC_DECLSPEC int hwloc_topology_export_xml(hwloc_topology_t topology, const char *xmlpath, unsigned long flags);
    -
    72
    -
    105HWLOC_DECLSPEC int hwloc_topology_export_xmlbuffer(hwloc_topology_t topology, char **xmlbuffer, int *buflen, unsigned long flags);
    -
    106
    -
    108HWLOC_DECLSPEC void hwloc_free_xmlbuffer(hwloc_topology_t topology, char *xmlbuffer);
    -
    109
    -
    128HWLOC_DECLSPEC void hwloc_topology_set_userdata_export_callback(hwloc_topology_t topology,
    -
    129 void (*export_cb)(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj));
    -
    130
    -
    158HWLOC_DECLSPEC int hwloc_export_obj_userdata(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length);
    -
    159
    -
    179HWLOC_DECLSPEC int hwloc_export_obj_userdata_base64(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length);
    -
    180
    -
    203HWLOC_DECLSPEC void hwloc_topology_set_userdata_import_callback(hwloc_topology_t topology,
    -
    204 void (*import_cb)(hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length));
    -
    205
    -
    217enum hwloc_topology_export_synthetic_flags_e {
    -
    223 HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_EXTENDED_TYPES = (1UL<<0),
    -
    224
    -
    231 HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_ATTRS = (1UL<<1),
    -
    232
    -
    241 HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_V1 = (1UL<<2),
    -
    242
    -
    251 HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_IGNORE_MEMORY = (1UL<<3)
    -
    252};
    -
    253
    -
    275 HWLOC_DECLSPEC int hwloc_topology_export_synthetic(hwloc_topology_t topology, char *buffer, size_t buflen, unsigned long flags);
    -
    276
    -
    281#ifdef __cplusplus
    -
    282} /* extern "C" */
    -
    283#endif
    -
    284
    -
    285
    -
    286#endif /* HWLOC_EXPORT_H */
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:716
    -
    hwloc_topology_export_xml_flags_e
    hwloc_topology_export_xml_flags_e
    Flags for exporting XML topologies.
    Definition: export.h:35
    -
    hwloc_export_obj_userdata_base64
    int hwloc_export_obj_userdata_base64(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length)
    Encode and export some object userdata to XML.
    -
    hwloc_free_xmlbuffer
    void hwloc_free_xmlbuffer(hwloc_topology_t topology, char *xmlbuffer)
    Free a buffer allocated by hwloc_topology_export_xmlbuffer()
    -
    hwloc_topology_export_xml
    int hwloc_topology_export_xml(hwloc_topology_t topology, const char *xmlpath, unsigned long flags)
    Export the topology into an XML file.
    -
    hwloc_topology_set_userdata_import_callback
    void hwloc_topology_set_userdata_import_callback(hwloc_topology_t topology, void(*import_cb)(hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length))
    Set the application-specific callback for importing userdata.
    -
    hwloc_topology_set_userdata_export_callback
    void hwloc_topology_set_userdata_export_callback(hwloc_topology_t topology, void(*export_cb)(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj))
    Set the application-specific callback for exporting object userdata.
    -
    hwloc_export_obj_userdata
    int hwloc_export_obj_userdata(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length)
    Export some object userdata to XML.
    -
    hwloc_topology_export_xmlbuffer
    int hwloc_topology_export_xmlbuffer(hwloc_topology_t topology, char **xmlbuffer, int *buflen, unsigned long flags)
    Export the topology into a newly-allocated XML memory buffer.
    -
    HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1
    @ HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1
    Export XML that is loadable by hwloc v1.x. However, the export may miss some details about the topolo...
    Definition: export.h:40
    -
    hwloc_topology_export_synthetic
    int hwloc_topology_export_synthetic(hwloc_topology_t topology, char *buffer, size_t buflen, unsigned long flags)
    Export the topology as a synthetic string.
    -
    hwloc_topology_export_synthetic_flags_e
    hwloc_topology_export_synthetic_flags_e
    Flags for exporting synthetic topologies.
    Definition: export.h:217
    -
    HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_IGNORE_MEMORY
    @ HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_IGNORE_MEMORY
    Do not export memory information.
    Definition: export.h:251
    -
    HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_EXTENDED_TYPES
    @ HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_EXTENDED_TYPES
    Export extended types such as L2dcache as basic types such as Cache.
    Definition: export.h:223
    -
    HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_V1
    @ HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_V1
    Export the memory hierarchy as expected in hwloc 1.x.
    Definition: export.h:241
    -
    HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_ATTRS
    @ HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_ATTRS
    Do not export level attributes.
    Definition: export.h:231
    -
    hwloc_obj
    Structure of a topology object.
    Definition: hwloc.h:420
    -
    - - - - - - - - -
    -
    distances.h
    -
    -
    -
    1/*
    -
    2 * Copyright © 2010-2023 Inria. All rights reserved.
    -
    3 * See COPYING in top-level directory.
    -
    4 */
    -
    5
    -
    10#ifndef HWLOC_DISTANCES_H
    -
    11#define HWLOC_DISTANCES_H
    -
    12
    -
    13#ifndef HWLOC_H
    -
    14#error Please include the main hwloc.h instead
    -
    15#endif
    -
    16
    -
    17
    -
    18#ifdef __cplusplus
    -
    19extern "C" {
    -
    20#elif 0
    -
    21}
    -
    22#endif
    -
    23
    -
    24
    -
    53struct hwloc_distances_s {
    -
    54 unsigned nbobjs;
    -
    55 hwloc_obj_t *objs;
    -
    60 unsigned long kind;
    -
    61 hwloc_uint64_t *values;
    -
    66};
    -
    67
    -
    79enum hwloc_distances_kind_e {
    -
    83 HWLOC_DISTANCES_KIND_FROM_OS = (1UL<<0),
    -
    87 HWLOC_DISTANCES_KIND_FROM_USER = (1UL<<1),
    -
    88
    -
    95 HWLOC_DISTANCES_KIND_MEANS_LATENCY = (1UL<<2),
    -
    102 HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH = (1UL<<3),
    -
    103
    -
    109 HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES = (1UL<<4)
    -
    110};
    -
    111
    -
    137HWLOC_DECLSPEC int
    -
    138hwloc_distances_get(hwloc_topology_t topology,
    -
    139 unsigned *nr, struct hwloc_distances_s **distances,
    -
    140 unsigned long kind, unsigned long flags);
    -
    141
    -
    148HWLOC_DECLSPEC int
    -
    149hwloc_distances_get_by_depth(hwloc_topology_t topology, int depth,
    -
    150 unsigned *nr, struct hwloc_distances_s **distances,
    -
    151 unsigned long kind, unsigned long flags);
    -
    152
    -
    159HWLOC_DECLSPEC int
    -
    160hwloc_distances_get_by_type(hwloc_topology_t topology, hwloc_obj_type_t type,
    -
    161 unsigned *nr, struct hwloc_distances_s **distances,
    -
    162 unsigned long kind, unsigned long flags);
    -
    163
    -
    174HWLOC_DECLSPEC int
    -
    175hwloc_distances_get_by_name(hwloc_topology_t topology, const char *name,
    -
    176 unsigned *nr, struct hwloc_distances_s **distances,
    -
    177 unsigned long flags);
    -
    178
    -
    189HWLOC_DECLSPEC const char *
    -
    190hwloc_distances_get_name(hwloc_topology_t topology, struct hwloc_distances_s *distances);
    -
    191
    -
    196HWLOC_DECLSPEC void
    -
    197hwloc_distances_release(hwloc_topology_t topology, struct hwloc_distances_s *distances);
    -
    198
    -
    200enum hwloc_distances_transform_e {
    -
    214 HWLOC_DISTANCES_TRANSFORM_REMOVE_NULL = 0,
    -
    215
    -
    228 HWLOC_DISTANCES_TRANSFORM_LINKS = 1,
    -
    229
    -
    237 HWLOC_DISTANCES_TRANSFORM_MERGE_SWITCH_PORTS = 2,
    -
    238
    -
    244 HWLOC_DISTANCES_TRANSFORM_TRANSITIVE_CLOSURE = 3
    -
    245};
    -
    246
    -
    275HWLOC_DECLSPEC int hwloc_distances_transform(hwloc_topology_t topology, struct hwloc_distances_s *distances,
    -
    276 enum hwloc_distances_transform_e transform,
    -
    277 void *transform_attr,
    -
    278 unsigned long flags);
    -
    279
    -
    293static __hwloc_inline int
    -
    294hwloc_distances_obj_index(struct hwloc_distances_s *distances, hwloc_obj_t obj)
    -
    295{
    -
    296 unsigned i;
    -
    297 for(i=0; i<distances->nbobjs; i++)
    -
    298 if (distances->objs[i] == obj)
    -
    299 return (int)i;
    -
    300 return -1;
    -
    301}
    -
    302
    -
    311static __hwloc_inline int
    -
    312hwloc_distances_obj_pair_values(struct hwloc_distances_s *distances,
    -
    313 hwloc_obj_t obj1, hwloc_obj_t obj2,
    -
    314 hwloc_uint64_t *value1to2, hwloc_uint64_t *value2to1)
    -
    315{
    -
    316 int i1 = hwloc_distances_obj_index(distances, obj1);
    -
    317 int i2 = hwloc_distances_obj_index(distances, obj2);
    -
    318 if (i1 < 0 || i2 < 0)
    -
    319 return -1;
    -
    320 *value1to2 = distances->values[i1 * distances->nbobjs + i2];
    -
    321 *value2to1 = distances->values[i2 * distances->nbobjs + i1];
    -
    322 return 0;
    -
    323}
    -
    324
    -
    348typedef void * hwloc_distances_add_handle_t;
    -
    349
    -
    370HWLOC_DECLSPEC hwloc_distances_add_handle_t
    -
    371hwloc_distances_add_create(hwloc_topology_t topology,
    -
    372 const char *name, unsigned long kind,
    -
    373 unsigned long flags);
    -
    374
    -
    397HWLOC_DECLSPEC int hwloc_distances_add_values(hwloc_topology_t topology,
    -
    398 hwloc_distances_add_handle_t handle,
    -
    399 unsigned nbobjs, hwloc_obj_t *objs,
    -
    400 hwloc_uint64_t *values,
    -
    401 unsigned long flags);
    -
    402
    -
    404enum hwloc_distances_add_flag_e {
    -
    409 HWLOC_DISTANCES_ADD_FLAG_GROUP = (1UL<<0),
    -
    415 HWLOC_DISTANCES_ADD_FLAG_GROUP_INACCURATE = (1UL<<1)
    -
    416};
    -
    417
    -
    434HWLOC_DECLSPEC int hwloc_distances_add_commit(hwloc_topology_t topology,
    -
    435 hwloc_distances_add_handle_t handle,
    -
    436 unsigned long flags);
    -
    437
    -
    456HWLOC_DECLSPEC int hwloc_distances_remove(hwloc_topology_t topology);
    -
    457
    -
    464HWLOC_DECLSPEC int hwloc_distances_remove_by_depth(hwloc_topology_t topology, int depth);
    -
    465
    -
    472static __hwloc_inline int
    -
    473hwloc_distances_remove_by_type(hwloc_topology_t topology, hwloc_obj_type_t type)
    -
    474{
    -
    475 int depth = hwloc_get_type_depth(topology, type);
    -
    476 if (depth == HWLOC_TYPE_DEPTH_UNKNOWN || depth == HWLOC_TYPE_DEPTH_MULTIPLE)
    -
    477 return 0;
    -
    478 return hwloc_distances_remove_by_depth(topology, depth);
    -
    479}
    -
    480
    -
    487HWLOC_DECLSPEC int hwloc_distances_release_remove(hwloc_topology_t topology, struct hwloc_distances_s *distances);
    -
    488
    -
    492#ifdef __cplusplus
    -
    493} /* extern "C" */
    -
    494#endif
    -
    495
    -
    496
    -
    497#endif /* HWLOC_DISTANCES_H */
    -
    hwloc_obj_type_t
    hwloc_obj_type_t
    Type of topology object.
    Definition: hwloc.h:197
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:716
    -
    hwloc_get_type_depth
    int hwloc_get_type_depth(hwloc_topology_t topology, hwloc_obj_type_t type)
    Returns the depth of objects of type type.
    -
    HWLOC_TYPE_DEPTH_UNKNOWN
    @ HWLOC_TYPE_DEPTH_UNKNOWN
    No object of given type exists in the topology.
    Definition: hwloc.h:853
    -
    HWLOC_TYPE_DEPTH_MULTIPLE
    @ HWLOC_TYPE_DEPTH_MULTIPLE
    Objects of given type exist at different depth in the topology (only for Groups).
    Definition: hwloc.h:854
    -
    hwloc_distances_release
    void hwloc_distances_release(hwloc_topology_t topology, struct hwloc_distances_s *distances)
    Release a distance matrix structure previously returned by hwloc_distances_get().
    -
    hwloc_distances_transform_e
    hwloc_distances_transform_e
    Transformations of distances structures.
    Definition: distances.h:200
    -
    hwloc_distances_get_by_depth
    int hwloc_distances_get_by_depth(hwloc_topology_t topology, int depth, unsigned *nr, struct hwloc_distances_s **distances, unsigned long kind, unsigned long flags)
    Retrieve distance matrices for object at a specific depth in the topology.
    -
    hwloc_distances_get
    int hwloc_distances_get(hwloc_topology_t topology, unsigned *nr, struct hwloc_distances_s **distances, unsigned long kind, unsigned long flags)
    Retrieve distance matrices.
    -
    hwloc_distances_get_by_name
    int hwloc_distances_get_by_name(hwloc_topology_t topology, const char *name, unsigned *nr, struct hwloc_distances_s **distances, unsigned long flags)
    Retrieve a distance matrix with the given name.
    -
    hwloc_distances_get_by_type
    int hwloc_distances_get_by_type(hwloc_topology_t topology, hwloc_obj_type_t type, unsigned *nr, struct hwloc_distances_s **distances, unsigned long kind, unsigned long flags)
    Retrieve distance matrices for object of a specific type.
    -
    hwloc_distances_kind_e
    hwloc_distances_kind_e
    Kinds of distance matrices.
    Definition: distances.h:79
    -
    hwloc_distances_transform
    int hwloc_distances_transform(hwloc_topology_t topology, struct hwloc_distances_s *distances, enum hwloc_distances_transform_e transform, void *transform_attr, unsigned long flags)
    Apply a transformation to a distances structure.
    -
    hwloc_distances_get_name
    const char * hwloc_distances_get_name(hwloc_topology_t topology, struct hwloc_distances_s *distances)
    Get a description of what a distances structure contains.
    -
    HWLOC_DISTANCES_TRANSFORM_TRANSITIVE_CLOSURE
    @ HWLOC_DISTANCES_TRANSFORM_TRANSITIVE_CLOSURE
    Apply a transitive closure to the matrix to connect objects across switches. This currently only appl...
    Definition: distances.h:244
    -
    HWLOC_DISTANCES_TRANSFORM_MERGE_SWITCH_PORTS
    @ HWLOC_DISTANCES_TRANSFORM_MERGE_SWITCH_PORTS
    Merge switches with multiple ports into a single object. This currently only applies to NVSwitches wh...
    Definition: distances.h:237
    -
    HWLOC_DISTANCES_TRANSFORM_LINKS
    @ HWLOC_DISTANCES_TRANSFORM_LINKS
    Replace bandwidth values with a number of links.
    Definition: distances.h:228
    -
    HWLOC_DISTANCES_TRANSFORM_REMOVE_NULL
    @ HWLOC_DISTANCES_TRANSFORM_REMOVE_NULL
    Remove NULL objects from the distances structure.
    Definition: distances.h:214
    -
    HWLOC_DISTANCES_KIND_FROM_USER
    @ HWLOC_DISTANCES_KIND_FROM_USER
    These distances were provided by the user.
    Definition: distances.h:87
    -
    HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH
    @ HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH
    Distance values are similar to bandwidths between objects. Values are higher for closer objects,...
    Definition: distances.h:102
    -
    HWLOC_DISTANCES_KIND_FROM_OS
    @ HWLOC_DISTANCES_KIND_FROM_OS
    These distances were obtained from the operating system or hardware.
    Definition: distances.h:83
    -
    HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES
    @ HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES
    This distances structure covers objects of different types. This may apply to the "NVLinkBandwidth" s...
    Definition: distances.h:109
    -
    HWLOC_DISTANCES_KIND_MEANS_LATENCY
    @ HWLOC_DISTANCES_KIND_MEANS_LATENCY
    Distance values are similar to latencies between objects. Values are smaller for closer objects,...
    Definition: distances.h:95
    -
    hwloc_distances_obj_pair_values
    static int hwloc_distances_obj_pair_values(struct hwloc_distances_s *distances, hwloc_obj_t obj1, hwloc_obj_t obj2, hwloc_uint64_t *value1to2, hwloc_uint64_t *value2to1)
    Find the values between two objects in a distance matrices.
    Definition: distances.h:312
    -
    hwloc_distances_obj_index
    static int hwloc_distances_obj_index(struct hwloc_distances_s *distances, hwloc_obj_t obj)
    Find the index of an object in a distances structure.
    Definition: distances.h:294
    -
    hwloc_distances_add_commit
    int hwloc_distances_add_commit(hwloc_topology_t topology, hwloc_distances_add_handle_t handle, unsigned long flags)
    Commit a new distances structure.
    -
    hwloc_distances_add_flag_e
    hwloc_distances_add_flag_e
    Flags for adding a new distances to a topology.
    Definition: distances.h:404
    -
    hwloc_distances_add_handle_t
    void * hwloc_distances_add_handle_t
    Handle to a new distances structure during its addition to the topology.
    Definition: distances.h:348
    -
    hwloc_distances_add_create
    hwloc_distances_add_handle_t hwloc_distances_add_create(hwloc_topology_t topology, const char *name, unsigned long kind, unsigned long flags)
    Create a new empty distances structure.
    -
    hwloc_distances_add_values
    int hwloc_distances_add_values(hwloc_topology_t topology, hwloc_distances_add_handle_t handle, unsigned nbobjs, hwloc_obj_t *objs, hwloc_uint64_t *values, unsigned long flags)
    Specify the objects and values in a new empty distances structure.
    -
    HWLOC_DISTANCES_ADD_FLAG_GROUP_INACCURATE
    @ HWLOC_DISTANCES_ADD_FLAG_GROUP_INACCURATE
    If grouping, consider the distance values as inaccurate and relax the comparisons during the grouping...
    Definition: distances.h:415
    -
    HWLOC_DISTANCES_ADD_FLAG_GROUP
    @ HWLOC_DISTANCES_ADD_FLAG_GROUP
    Try to group objects based on the newly provided distance information. This is ignored for distances ...
    Definition: distances.h:409
    -
    hwloc_distances_release_remove
    int hwloc_distances_release_remove(hwloc_topology_t topology, struct hwloc_distances_s *distances)
    Release and remove the given distance matrice from the topology.
    -
    hwloc_distances_remove_by_type
    static int hwloc_distances_remove_by_type(hwloc_topology_t topology, hwloc_obj_type_t type)
    Remove distance matrices for objects of a specific type in the topology.
    Definition: distances.h:473
    -
    hwloc_distances_remove_by_depth
    int hwloc_distances_remove_by_depth(hwloc_topology_t topology, int depth)
    Remove distance matrices for objects at a specific depth in the topology.
    -
    hwloc_distances_remove
    int hwloc_distances_remove(hwloc_topology_t topology)
    Remove all distance matrices from a topology.
    -
    hwloc_obj
    Structure of a topology object.
    Definition: hwloc.h:420
    -
    hwloc_distances_s
    Matrix of distances between a set of objects.
    Definition: distances.h:53
    -
    hwloc_distances_s::nbobjs
    unsigned nbobjs
    Number of objects described by the distance matrix.
    Definition: distances.h:54
    -
    hwloc_distances_s::values
    hwloc_uint64_t * values
    Matrix of distances between objects, stored as a one-dimension array.
    Definition: distances.h:61
    -
    hwloc_distances_s::kind
    unsigned long kind
    OR'ed set of hwloc_distances_kind_e.
    Definition: distances.h:60
    -
    hwloc_distances_s::objs
    hwloc_obj_t * objs
    Array of objects described by the distance matrix. These objects are not in any particular order,...
    Definition: distances.h:55
    -
    - - - - - - - - -
    -
    memattrs.h
    -
    -
    -
    1/*
    -
    2 * Copyright © 2019-2023 Inria. All rights reserved.
    -
    3 * See COPYING in top-level directory.
    -
    4 */
    -
    5
    -
    10#ifndef HWLOC_MEMATTR_H
    -
    11#define HWLOC_MEMATTR_H
    -
    12
    -
    13#include "hwloc.h"
    -
    14
    -
    15#ifdef __cplusplus
    -
    16extern "C" {
    -
    17#elif 0
    -
    18}
    -
    19#endif
    -
    20
    -
    69enum hwloc_memattr_id_e {
    -
    79 HWLOC_MEMATTR_ID_CAPACITY = 0,
    -
    80
    -
    94 HWLOC_MEMATTR_ID_LOCALITY = 1,
    -
    95
    -
    109 HWLOC_MEMATTR_ID_BANDWIDTH = 2,
    -
    110
    -
    120 HWLOC_MEMATTR_ID_READ_BANDWIDTH = 4,
    -
    121
    -
    131 HWLOC_MEMATTR_ID_WRITE_BANDWIDTH = 5,
    -
    132
    -
    146 HWLOC_MEMATTR_ID_LATENCY = 3,
    -
    147
    -
    157 HWLOC_MEMATTR_ID_READ_LATENCY = 6,
    -
    158
    -
    168 HWLOC_MEMATTR_ID_WRITE_LATENCY = 7,
    -
    169
    -
    170 /* TODO persistence? */
    -
    171
    -
    172 HWLOC_MEMATTR_ID_MAX
    -
    173};
    -
    174
    -
    178typedef unsigned hwloc_memattr_id_t;
    -
    179
    -
    185HWLOC_DECLSPEC int
    -
    186hwloc_memattr_get_by_name(hwloc_topology_t topology,
    -
    187 const char *name,
    -
    188 hwloc_memattr_id_t *id);
    -
    189
    -
    190
    -
    192enum hwloc_location_type_e {
    -
    194 HWLOC_LOCATION_TYPE_CPUSET = 1,
    -
    196 HWLOC_LOCATION_TYPE_OBJECT = 0
    -
    197};
    -
    198
    -
    200struct hwloc_location {
    -
    202 enum hwloc_location_type_e type;
    -
    204 union hwloc_location_u {
    -
    206 hwloc_cpuset_t cpuset;
    -
    208 hwloc_obj_t object;
    -
    209 } location;
    -
    210};
    -
    211
    -
    212
    -
    214enum hwloc_local_numanode_flag_e {
    -
    220 HWLOC_LOCAL_NUMANODE_FLAG_LARGER_LOCALITY = (1UL<<0),
    -
    221
    -
    227 HWLOC_LOCAL_NUMANODE_FLAG_SMALLER_LOCALITY = (1UL<<1),
    -
    228
    -
    233 HWLOC_LOCAL_NUMANODE_FLAG_ALL = (1UL<<2)
    -
    234};
    -
    235
    -
    267HWLOC_DECLSPEC int
    -
    268hwloc_get_local_numanode_objs(hwloc_topology_t topology,
    -
    269 struct hwloc_location *location,
    -
    270 unsigned *nr,
    -
    271 hwloc_obj_t *nodes,
    -
    272 unsigned long flags);
    -
    273
    -
    274
    -
    275
    -
    294HWLOC_DECLSPEC int
    -
    295hwloc_memattr_get_value(hwloc_topology_t topology,
    -
    296 hwloc_memattr_id_t attribute,
    -
    297 hwloc_obj_t target_node,
    -
    298 struct hwloc_location *initiator,
    -
    299 unsigned long flags,
    -
    300 hwloc_uint64_t *value);
    -
    301
    -
    330HWLOC_DECLSPEC int
    -
    331hwloc_memattr_get_best_target(hwloc_topology_t topology,
    -
    332 hwloc_memattr_id_t attribute,
    -
    333 struct hwloc_location *initiator,
    -
    334 unsigned long flags,
    -
    335 hwloc_obj_t *best_target, hwloc_uint64_t *value);
    -
    336
    -
    358HWLOC_DECLSPEC int
    -
    359hwloc_memattr_get_best_initiator(hwloc_topology_t topology,
    -
    360 hwloc_memattr_id_t attribute,
    -
    361 hwloc_obj_t target,
    -
    362 unsigned long flags,
    -
    363 struct hwloc_location *best_initiator, hwloc_uint64_t *value);
    -
    364
    -
    377HWLOC_DECLSPEC int
    -
    378hwloc_memattr_get_name(hwloc_topology_t topology,
    -
    379 hwloc_memattr_id_t attribute,
    -
    380 const char **name);
    -
    381
    -
    389HWLOC_DECLSPEC int
    -
    390hwloc_memattr_get_flags(hwloc_topology_t topology,
    -
    391 hwloc_memattr_id_t attribute,
    -
    392 unsigned long *flags);
    -
    393
    -
    397enum hwloc_memattr_flag_e {
    -
    401 HWLOC_MEMATTR_FLAG_HIGHER_FIRST = (1UL<<0),
    -
    405 HWLOC_MEMATTR_FLAG_LOWER_FIRST = (1UL<<1),
    -
    409 HWLOC_MEMATTR_FLAG_NEED_INITIATOR = (1UL<<2)
    -
    410};
    -
    411
    -
    421HWLOC_DECLSPEC int
    -
    422hwloc_memattr_register(hwloc_topology_t topology,
    -
    423 const char *name,
    -
    424 unsigned long flags,
    -
    425 hwloc_memattr_id_t *id);
    -
    426
    -
    447HWLOC_DECLSPEC int
    -
    448hwloc_memattr_set_value(hwloc_topology_t topology,
    -
    449 hwloc_memattr_id_t attribute,
    -
    450 hwloc_obj_t target_node,
    -
    451 struct hwloc_location *initiator,
    -
    452 unsigned long flags,
    -
    453 hwloc_uint64_t value);
    -
    454
    -
    493HWLOC_DECLSPEC int
    -
    494hwloc_memattr_get_targets(hwloc_topology_t topology,
    -
    495 hwloc_memattr_id_t attribute,
    -
    496 struct hwloc_location *initiator,
    -
    497 unsigned long flags,
    -
    498 unsigned *nr, hwloc_obj_t *targets, hwloc_uint64_t *values);
    -
    499
    -
    531HWLOC_DECLSPEC int
    -
    532hwloc_memattr_get_initiators(hwloc_topology_t topology,
    -
    533 hwloc_memattr_id_t attribute,
    -
    534 hwloc_obj_t target_node,
    -
    535 unsigned long flags,
    -
    536 unsigned *nr, struct hwloc_location *initiators, hwloc_uint64_t *values);
    -
    539#ifdef __cplusplus
    -
    540} /* extern "C" */
    -
    541#endif
    -
    542
    -
    543
    -
    544#endif /* HWLOC_MEMATTR_H */
    -
    hwloc_cpuset_t
    hwloc_bitmap_t hwloc_cpuset_t
    A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
    Definition: hwloc.h:161
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:716
    -
    hwloc_memattr_get_value
    int hwloc_memattr_get_value(hwloc_topology_t topology, hwloc_memattr_id_t attribute, hwloc_obj_t target_node, struct hwloc_location *initiator, unsigned long flags, hwloc_uint64_t *value)
    Return an attribute value for a specific target NUMA node.
    -
    hwloc_location_type_e
    hwloc_location_type_e
    Type of location.
    Definition: memattrs.h:192
    -
    hwloc_get_local_numanode_objs
    int hwloc_get_local_numanode_objs(hwloc_topology_t topology, struct hwloc_location *location, unsigned *nr, hwloc_obj_t *nodes, unsigned long flags)
    Return an array of local NUMA nodes.
    -
    hwloc_memattr_get_by_name
    int hwloc_memattr_get_by_name(hwloc_topology_t topology, const char *name, hwloc_memattr_id_t *id)
    Return the identifier of the memory attribute with the given name.
    -
    hwloc_memattr_get_best_target
    int hwloc_memattr_get_best_target(hwloc_topology_t topology, hwloc_memattr_id_t attribute, struct hwloc_location *initiator, unsigned long flags, hwloc_obj_t *best_target, hwloc_uint64_t *value)
    Return the best target NUMA node for the given attribute and initiator.
    -
    hwloc_memattr_get_best_initiator
    int hwloc_memattr_get_best_initiator(hwloc_topology_t topology, hwloc_memattr_id_t attribute, hwloc_obj_t target, unsigned long flags, struct hwloc_location *best_initiator, hwloc_uint64_t *value)
    Return the best initiator for the given attribute and target NUMA node.
    -
    hwloc_memattr_id_e
    hwloc_memattr_id_e
    Memory node attributes.
    Definition: memattrs.h:69
    -
    hwloc_local_numanode_flag_e
    hwloc_local_numanode_flag_e
    Flags for selecting target NUMA nodes.
    Definition: memattrs.h:214
    -
    hwloc_memattr_id_t
    unsigned hwloc_memattr_id_t
    A memory attribute identifier. May be either one of hwloc_memattr_id_e or a new id returned by hwloc_...
    Definition: memattrs.h:178
    -
    HWLOC_LOCATION_TYPE_CPUSET
    @ HWLOC_LOCATION_TYPE_CPUSET
    Location is given as a cpuset, in the location cpuset union field.
    Definition: memattrs.h:194
    -
    HWLOC_LOCATION_TYPE_OBJECT
    @ HWLOC_LOCATION_TYPE_OBJECT
    Location is given as an object, in the location object union field.
    Definition: memattrs.h:196
    -
    HWLOC_MEMATTR_ID_BANDWIDTH
    @ HWLOC_MEMATTR_ID_BANDWIDTH
    The "Bandwidth" is returned in MiB/s, as seen from the given initiator location.
    Definition: memattrs.h:109
    -
    HWLOC_MEMATTR_ID_WRITE_BANDWIDTH
    @ HWLOC_MEMATTR_ID_WRITE_BANDWIDTH
    The "WriteBandwidth" is returned in MiB/s, as seen from the given initiator location.
    Definition: memattrs.h:131
    -
    HWLOC_MEMATTR_ID_READ_LATENCY
    @ HWLOC_MEMATTR_ID_READ_LATENCY
    The "ReadLatency" is returned as nanoseconds, as seen from the given initiator location.
    Definition: memattrs.h:157
    -
    HWLOC_MEMATTR_ID_LOCALITY
    @ HWLOC_MEMATTR_ID_LOCALITY
    The "Locality" is returned as the number of PUs in that locality (e.g. the weight of its cpuset).
    Definition: memattrs.h:94
    -
    HWLOC_MEMATTR_ID_CAPACITY
    @ HWLOC_MEMATTR_ID_CAPACITY
    The "Capacity" is returned in bytes (local_memory attribute in objects).
    Definition: memattrs.h:79
    -
    HWLOC_MEMATTR_ID_WRITE_LATENCY
    @ HWLOC_MEMATTR_ID_WRITE_LATENCY
    The "WriteLatency" is returned as nanoseconds, as seen from the given initiator location.
    Definition: memattrs.h:168
    -
    HWLOC_MEMATTR_ID_READ_BANDWIDTH
    @ HWLOC_MEMATTR_ID_READ_BANDWIDTH
    The "ReadBandwidth" is returned in MiB/s, as seen from the given initiator location.
    Definition: memattrs.h:120
    -
    HWLOC_MEMATTR_ID_LATENCY
    @ HWLOC_MEMATTR_ID_LATENCY
    The "Latency" is returned as nanoseconds, as seen from the given initiator location.
    Definition: memattrs.h:146
    -
    HWLOC_LOCAL_NUMANODE_FLAG_LARGER_LOCALITY
    @ HWLOC_LOCAL_NUMANODE_FLAG_LARGER_LOCALITY
    Select NUMA nodes whose locality is larger than the given cpuset. For instance, if a single PU (or it...
    Definition: memattrs.h:220
    -
    HWLOC_LOCAL_NUMANODE_FLAG_SMALLER_LOCALITY
    @ HWLOC_LOCAL_NUMANODE_FLAG_SMALLER_LOCALITY
    Select NUMA nodes whose locality is smaller than the given cpuset. For instance, if a package (or its...
    Definition: memattrs.h:227
    -
    HWLOC_LOCAL_NUMANODE_FLAG_ALL
    @ HWLOC_LOCAL_NUMANODE_FLAG_ALL
    Select all NUMA nodes in the topology. The initiator initiator is ignored.
    Definition: memattrs.h:233
    -
    hwloc_memattr_get_initiators
    int hwloc_memattr_get_initiators(hwloc_topology_t topology, hwloc_memattr_id_t attribute, hwloc_obj_t target_node, unsigned long flags, unsigned *nr, struct hwloc_location *initiators, hwloc_uint64_t *values)
    Return the initiators that have values for a given attribute for a specific target NUMA node.
    -
    hwloc_memattr_get_flags
    int hwloc_memattr_get_flags(hwloc_topology_t topology, hwloc_memattr_id_t attribute, unsigned long *flags)
    Return the flags of the given attribute.
    -
    hwloc_memattr_get_name
    int hwloc_memattr_get_name(hwloc_topology_t topology, hwloc_memattr_id_t attribute, const char **name)
    Return the name of a memory attribute.
    -
    hwloc_memattr_register
    int hwloc_memattr_register(hwloc_topology_t topology, const char *name, unsigned long flags, hwloc_memattr_id_t *id)
    Register a new memory attribute.
    -
    hwloc_memattr_flag_e
    hwloc_memattr_flag_e
    Memory attribute flags. Given to hwloc_memattr_register() and returned by hwloc_memattr_get_flags().
    Definition: memattrs.h:397
    -
    hwloc_memattr_set_value
    int hwloc_memattr_set_value(hwloc_topology_t topology, hwloc_memattr_id_t attribute, hwloc_obj_t target_node, struct hwloc_location *initiator, unsigned long flags, hwloc_uint64_t value)
    Set an attribute value for a specific target NUMA node.
    -
    hwloc_memattr_get_targets
    int hwloc_memattr_get_targets(hwloc_topology_t topology, hwloc_memattr_id_t attribute, struct hwloc_location *initiator, unsigned long flags, unsigned *nr, hwloc_obj_t *targets, hwloc_uint64_t *values)
    Return the target NUMA nodes that have some values for a given attribute.
    -
    HWLOC_MEMATTR_FLAG_LOWER_FIRST
    @ HWLOC_MEMATTR_FLAG_LOWER_FIRST
    The best nodes for this memory attribute are those with the lower values. For instance Latency.
    Definition: memattrs.h:405
    -
    HWLOC_MEMATTR_FLAG_NEED_INITIATOR
    @ HWLOC_MEMATTR_FLAG_NEED_INITIATOR
    The value returned for this memory attribute depends on the given initiator. For instance Bandwidth a...
    Definition: memattrs.h:409
    -
    HWLOC_MEMATTR_FLAG_HIGHER_FIRST
    @ HWLOC_MEMATTR_FLAG_HIGHER_FIRST
    The best nodes for this memory attribute are those with the higher values. For instance Bandwidth.
    Definition: memattrs.h:401
    -
    hwloc_obj
    Structure of a topology object.
    Definition: hwloc.h:420
    -
    hwloc_location
    Where to measure attributes from.
    Definition: memattrs.h:200
    -
    hwloc_location::location
    union hwloc_location::hwloc_location_u location
    -
    hwloc_location::type
    enum hwloc_location_type_e type
    Type of location.
    Definition: memattrs.h:202
    -
    hwloc_location::hwloc_location_u
    Actual location.
    Definition: memattrs.h:204
    -
    hwloc_location::hwloc_location_u::cpuset
    hwloc_cpuset_t cpuset
    Location as a cpuset, when the location type is HWLOC_LOCATION_TYPE_CPUSET.
    Definition: memattrs.h:206
    -
    hwloc_location::hwloc_location_u::object
    hwloc_obj_t object
    Location as an object, when the location type is HWLOC_LOCATION_TYPE_OBJECT.
    Definition: memattrs.h:208
    -
    - - - - - - - - -
    -
    cpukinds.h
    -
    -
    -
    1/*
    -
    2 * Copyright © 2020-2021 Inria. All rights reserved.
    -
    3 * See COPYING in top-level directory.
    -
    4 */
    -
    5
    -
    10#ifndef HWLOC_CPUKINDS_H
    -
    11#define HWLOC_CPUKINDS_H
    -
    12
    -
    13#include "hwloc.h"
    -
    14
    -
    15#ifdef __cplusplus
    -
    16extern "C" {
    -
    17#elif 0
    -
    18}
    -
    19#endif
    -
    20
    -
    81HWLOC_DECLSPEC int
    -
    82hwloc_cpukinds_get_nr(hwloc_topology_t topology,
    -
    83 unsigned long flags);
    -
    84
    -
    96HWLOC_DECLSPEC int
    -
    97hwloc_cpukinds_get_by_cpuset(hwloc_topology_t topology,
    -
    98 hwloc_const_bitmap_t cpuset,
    -
    99 unsigned long flags);
    -
    100
    -
    134HWLOC_DECLSPEC int
    -
    135hwloc_cpukinds_get_info(hwloc_topology_t topology,
    -
    136 unsigned kind_index,
    -
    137 hwloc_bitmap_t cpuset,
    -
    138 int *efficiency,
    -
    139 unsigned *nr_infos, struct hwloc_info_s **infos,
    -
    140 unsigned long flags);
    -
    141
    -
    179HWLOC_DECLSPEC int
    -
    180hwloc_cpukinds_register(hwloc_topology_t topology,
    -
    181 hwloc_bitmap_t cpuset,
    -
    182 int forced_efficiency,
    -
    183 unsigned nr_infos, struct hwloc_info_s *infos,
    -
    184 unsigned long flags);
    -
    185
    -
    188#ifdef __cplusplus
    -
    189} /* extern "C" */
    -
    190#endif
    -
    191
    -
    192
    -
    193#endif /* HWLOC_CPUKINDS_H */
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:716
    -
    hwloc_bitmap_t
    struct hwloc_bitmap_s * hwloc_bitmap_t
    Set of bits represented as an opaque pointer to an internal bitmap.
    Definition: bitmap.h:69
    -
    hwloc_const_bitmap_t
    const struct hwloc_bitmap_s * hwloc_const_bitmap_t
    a non-modifiable hwloc_bitmap_t
    Definition: bitmap.h:71
    -
    hwloc_cpukinds_register
    int hwloc_cpukinds_register(hwloc_topology_t topology, hwloc_bitmap_t cpuset, int forced_efficiency, unsigned nr_infos, struct hwloc_info_s *infos, unsigned long flags)
    Register a kind of CPU in the topology.
    -
    hwloc_cpukinds_get_nr
    int hwloc_cpukinds_get_nr(hwloc_topology_t topology, unsigned long flags)
    Get the number of different kinds of CPU cores in the topology.
    -
    hwloc_cpukinds_get_info
    int hwloc_cpukinds_get_info(hwloc_topology_t topology, unsigned kind_index, hwloc_bitmap_t cpuset, int *efficiency, unsigned *nr_infos, struct hwloc_info_s **infos, unsigned long flags)
    Get the CPU set and infos about a CPU kind in the topology.
    -
    hwloc_cpukinds_get_by_cpuset
    int hwloc_cpukinds_get_by_cpuset(hwloc_topology_t topology, hwloc_const_bitmap_t cpuset, unsigned long flags)
    Get the index of the CPU kind that contains CPUs listed in cpuset.
    -
    hwloc_info_s
    Object info.
    Definition: hwloc.h:698
    -
    - - - - - - - - -
    -
    linux.h
    -
    -
    -
    1/*
    -
    2 * Copyright © 2009 CNRS
    -
    3 * Copyright © 2009-2023 Inria. All rights reserved.
    -
    4 * Copyright © 2009-2011 Université Bordeaux
    -
    5 * See COPYING in top-level directory.
    -
    6 */
    -
    7
    -
    15#ifndef HWLOC_LINUX_H
    -
    16#define HWLOC_LINUX_H
    -
    17
    -
    18#include "hwloc.h"
    -
    19
    -
    20#include <stdio.h>
    -
    21
    -
    22
    -
    23#ifdef __cplusplus
    -
    24extern "C" {
    -
    25#endif
    -
    26
    -
    27
    -
    46HWLOC_DECLSPEC int hwloc_linux_set_tid_cpubind(hwloc_topology_t topology, pid_t tid, hwloc_const_cpuset_t set);
    -
    47
    -
    62HWLOC_DECLSPEC int hwloc_linux_get_tid_cpubind(hwloc_topology_t topology, pid_t tid, hwloc_cpuset_t set);
    -
    63
    -
    74HWLOC_DECLSPEC int hwloc_linux_get_tid_last_cpu_location(hwloc_topology_t topology, pid_t tid, hwloc_bitmap_t set);
    -
    75
    -
    85HWLOC_DECLSPEC int hwloc_linux_read_path_as_cpumask(const char *path, hwloc_bitmap_t set);
    -
    86
    -
    90#ifdef __cplusplus
    -
    91} /* extern "C" */
    -
    92#endif
    -
    93
    -
    94
    -
    95#endif /* HWLOC_LINUX_H */
    -
    hwloc_const_cpuset_t
    hwloc_const_bitmap_t hwloc_const_cpuset_t
    A non-modifiable hwloc_cpuset_t.
    Definition: hwloc.h:163
    -
    hwloc_cpuset_t
    hwloc_bitmap_t hwloc_cpuset_t
    A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
    Definition: hwloc.h:161
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:716
    -
    hwloc_bitmap_t
    struct hwloc_bitmap_s * hwloc_bitmap_t
    Set of bits represented as an opaque pointer to an internal bitmap.
    Definition: bitmap.h:69
    -
    hwloc_linux_set_tid_cpubind
    int hwloc_linux_set_tid_cpubind(hwloc_topology_t topology, pid_t tid, hwloc_const_cpuset_t set)
    Bind a thread tid on cpus given in cpuset set.
    -
    hwloc_linux_get_tid_last_cpu_location
    int hwloc_linux_get_tid_last_cpu_location(hwloc_topology_t topology, pid_t tid, hwloc_bitmap_t set)
    Get the last physical CPU where thread tid ran.
    -
    hwloc_linux_get_tid_cpubind
    int hwloc_linux_get_tid_cpubind(hwloc_topology_t topology, pid_t tid, hwloc_cpuset_t set)
    Get the current binding of thread tid.
    -
    hwloc_linux_read_path_as_cpumask
    int hwloc_linux_read_path_as_cpumask(const char *path, hwloc_bitmap_t set)
    Convert a linux kernel cpumask file path into a hwloc bitmap set.
    -
    - - - - - - - - -
    -
    linux-libnuma.h
    -
    -
    -
    1/*
    -
    2 * Copyright © 2009 CNRS
    -
    3 * Copyright © 2009-2023 Inria. All rights reserved.
    -
    4 * Copyright © 2009-2010, 2012 Université Bordeaux
    -
    5 * See COPYING in top-level directory.
    -
    6 */
    -
    7
    -
    15#ifndef HWLOC_LINUX_LIBNUMA_H
    -
    16#define HWLOC_LINUX_LIBNUMA_H
    -
    17
    -
    18#include "hwloc.h"
    -
    19
    -
    20#include <numa.h>
    -
    21
    -
    22
    -
    23#ifdef __cplusplus
    -
    24extern "C" {
    -
    25#endif
    -
    26
    -
    27
    -
    56static __hwloc_inline int
    -
    57hwloc_cpuset_to_linux_libnuma_ulongs(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset,
    -
    58 unsigned long *mask, unsigned long *maxnode)
    -
    59{
    -
    60 int depth = hwloc_get_type_depth(topology, HWLOC_OBJ_NUMANODE);
    -
    61 unsigned long outmaxnode = -1;
    -
    62 hwloc_obj_t node = NULL;
    -
    63
    -
    64 /* round-up to the next ulong and clear all bytes */
    -
    65 *maxnode = (*maxnode + 8*sizeof(*mask) - 1) & ~(8*sizeof(*mask) - 1);
    -
    66 memset(mask, 0, *maxnode/8);
    -
    67
    -
    68 while ((node = hwloc_get_next_obj_covering_cpuset_by_depth(topology, cpuset, depth, node)) != NULL) {
    -
    69 if (node->os_index >= *maxnode)
    -
    70 continue;
    -
    71 mask[node->os_index/sizeof(*mask)/8] |= 1UL << (node->os_index % (sizeof(*mask)*8));
    -
    72 if (outmaxnode == (unsigned long) -1 || outmaxnode < node->os_index)
    -
    73 outmaxnode = node->os_index;
    -
    74 }
    -
    75
    -
    76 *maxnode = outmaxnode+1;
    -
    77 return 0;
    -
    78}
    -
    79
    -
    92static __hwloc_inline int
    -
    93hwloc_nodeset_to_linux_libnuma_ulongs(hwloc_topology_t topology, hwloc_const_nodeset_t nodeset,
    -
    94 unsigned long *mask, unsigned long *maxnode)
    -
    95{
    -
    96 int depth = hwloc_get_type_depth(topology, HWLOC_OBJ_NUMANODE);
    -
    97 unsigned long outmaxnode = -1;
    -
    98 hwloc_obj_t node = NULL;
    -
    99
    -
    100 /* round-up to the next ulong and clear all bytes */
    -
    101 *maxnode = (*maxnode + 8*sizeof(*mask) - 1) & ~(8*sizeof(*mask) - 1);
    -
    102 memset(mask, 0, *maxnode/8);
    -
    103
    -
    104 while ((node = hwloc_get_next_obj_by_depth(topology, depth, node)) != NULL) {
    -
    105 if (node->os_index >= *maxnode)
    -
    106 continue;
    -
    107 if (!hwloc_bitmap_isset(nodeset, node->os_index))
    -
    108 continue;
    -
    109 mask[node->os_index/sizeof(*mask)/8] |= 1UL << (node->os_index % (sizeof(*mask)*8));
    -
    110 if (outmaxnode == (unsigned long) -1 || outmaxnode < node->os_index)
    -
    111 outmaxnode = node->os_index;
    -
    112 }
    -
    113
    -
    114 *maxnode = outmaxnode+1;
    -
    115 return 0;
    -
    116}
    -
    117
    -
    130static __hwloc_inline int
    -
    131hwloc_cpuset_from_linux_libnuma_ulongs(hwloc_topology_t topology, hwloc_cpuset_t cpuset,
    -
    132 const unsigned long *mask, unsigned long maxnode)
    -
    133{
    -
    134 int depth = hwloc_get_type_depth(topology, HWLOC_OBJ_NUMANODE);
    -
    135 hwloc_obj_t node = NULL;
    -
    136 hwloc_bitmap_zero(cpuset);
    -
    137 while ((node = hwloc_get_next_obj_by_depth(topology, depth, node)) != NULL)
    -
    138 if (node->os_index < maxnode
    -
    139 && (mask[node->os_index/sizeof(*mask)/8] & (1UL << (node->os_index % (sizeof(*mask)*8)))))
    -
    140 if (hwloc_bitmap_or(cpuset, cpuset, node->cpuset) < 0)
    -
    141 return -1;
    -
    142 return 0;
    -
    143}
    -
    144
    -
    157static __hwloc_inline int
    -
    158hwloc_nodeset_from_linux_libnuma_ulongs(hwloc_topology_t topology, hwloc_nodeset_t nodeset,
    -
    159 const unsigned long *mask, unsigned long maxnode)
    -
    160{
    -
    161 int depth = hwloc_get_type_depth(topology, HWLOC_OBJ_NUMANODE);
    -
    162 hwloc_obj_t node = NULL;
    -
    163 hwloc_bitmap_zero(nodeset);
    -
    164 while ((node = hwloc_get_next_obj_by_depth(topology, depth, node)) != NULL)
    -
    165 if (node->os_index < maxnode
    -
    166 && (mask[node->os_index/sizeof(*mask)/8] & (1UL << (node->os_index % (sizeof(*mask)*8)))))
    -
    167 if (hwloc_bitmap_set(nodeset, node->os_index) < 0)
    -
    168 return -1;
    -
    169 return 0;
    -
    170}
    -
    171
    -
    201static __hwloc_inline struct bitmask *
    -
    202hwloc_cpuset_to_linux_libnuma_bitmask(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset) __hwloc_attribute_malloc;
    -
    203static __hwloc_inline struct bitmask *
    -
    204hwloc_cpuset_to_linux_libnuma_bitmask(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset)
    -
    205{
    -
    206 int depth = hwloc_get_type_depth(topology, HWLOC_OBJ_NUMANODE);
    -
    207 hwloc_obj_t node = NULL;
    -
    208 struct bitmask *bitmask = numa_allocate_cpumask();
    -
    209 if (!bitmask)
    -
    210 return NULL;
    -
    211 while ((node = hwloc_get_next_obj_covering_cpuset_by_depth(topology, cpuset, depth, node)) != NULL)
    -
    212 if (node->attr->numanode.local_memory)
    -
    213 numa_bitmask_setbit(bitmask, node->os_index);
    -
    214 return bitmask;
    -
    215}
    -
    216
    -
    226static __hwloc_inline struct bitmask *
    -
    227hwloc_nodeset_to_linux_libnuma_bitmask(hwloc_topology_t topology, hwloc_const_nodeset_t nodeset) __hwloc_attribute_malloc;
    -
    228static __hwloc_inline struct bitmask *
    -
    229hwloc_nodeset_to_linux_libnuma_bitmask(hwloc_topology_t topology, hwloc_const_nodeset_t nodeset)
    -
    230{
    -
    231 int depth = hwloc_get_type_depth(topology, HWLOC_OBJ_NUMANODE);
    -
    232 hwloc_obj_t node = NULL;
    -
    233 struct bitmask *bitmask = numa_allocate_cpumask();
    -
    234 if (!bitmask)
    -
    235 return NULL;
    -
    236 while ((node = hwloc_get_next_obj_by_depth(topology, depth, node)) != NULL)
    -
    237 if (hwloc_bitmap_isset(nodeset, node->os_index) && node->attr->numanode.local_memory)
    -
    238 numa_bitmask_setbit(bitmask, node->os_index);
    -
    239 return bitmask;
    -
    240}
    -
    241
    -
    250static __hwloc_inline int
    -
    251hwloc_cpuset_from_linux_libnuma_bitmask(hwloc_topology_t topology, hwloc_cpuset_t cpuset,
    -
    252 const struct bitmask *bitmask)
    -
    253{
    -
    254 int depth = hwloc_get_type_depth(topology, HWLOC_OBJ_NUMANODE);
    -
    255 hwloc_obj_t node = NULL;
    -
    256 hwloc_bitmap_zero(cpuset);
    -
    257 while ((node = hwloc_get_next_obj_by_depth(topology, depth, node)) != NULL)
    -
    258 if (numa_bitmask_isbitset(bitmask, node->os_index))
    -
    259 if (hwloc_bitmap_or(cpuset, cpuset, node->cpuset) < 0)
    -
    260 return -1;
    -
    261 return 0;
    -
    262}
    -
    263
    -
    272static __hwloc_inline int
    -
    273hwloc_nodeset_from_linux_libnuma_bitmask(hwloc_topology_t topology, hwloc_nodeset_t nodeset,
    -
    274 const struct bitmask *bitmask)
    -
    275{
    -
    276 int depth = hwloc_get_type_depth(topology, HWLOC_OBJ_NUMANODE);
    -
    277 hwloc_obj_t node = NULL;
    -
    278 hwloc_bitmap_zero(nodeset);
    -
    279 while ((node = hwloc_get_next_obj_by_depth(topology, depth, node)) != NULL)
    -
    280 if (numa_bitmask_isbitset(bitmask, node->os_index))
    -
    281 if (hwloc_bitmap_set(nodeset, node->os_index) < 0)
    -
    282 return -1;
    -
    283 return 0;
    -
    284}
    -
    285
    -
    289#ifdef __cplusplus
    -
    290} /* extern "C" */
    -
    291#endif
    -
    292
    -
    293
    -
    294#endif /* HWLOC_LINUX_NUMA_H */
    -
    hwloc_const_cpuset_t
    hwloc_const_bitmap_t hwloc_const_cpuset_t
    A non-modifiable hwloc_cpuset_t.
    Definition: hwloc.h:163
    -
    hwloc_const_nodeset_t
    hwloc_const_bitmap_t hwloc_const_nodeset_t
    A non-modifiable hwloc_nodeset_t.
    Definition: hwloc.h:181
    -
    hwloc_nodeset_t
    hwloc_bitmap_t hwloc_nodeset_t
    A node set is a bitmap whose bits are set according to NUMA memory node physical OS indexes.
    Definition: hwloc.h:178
    -
    hwloc_cpuset_t
    hwloc_bitmap_t hwloc_cpuset_t
    A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
    Definition: hwloc.h:161
    -
    HWLOC_OBJ_NUMANODE
    @ HWLOC_OBJ_NUMANODE
    NUMA node. An object that contains memory that is directly and byte-accessible to the host processors...
    Definition: hwloc.h:257
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:716
    -
    hwloc_get_type_depth
    int hwloc_get_type_depth(hwloc_topology_t topology, hwloc_obj_type_t type)
    Returns the depth of objects of type type.
    -
    hwloc_get_next_obj_by_depth
    static hwloc_obj_t hwloc_get_next_obj_by_depth(hwloc_topology_t topology, int depth, hwloc_obj_t prev)
    Returns the next object at depth depth.
    -
    hwloc_get_next_obj_covering_cpuset_by_depth
    static hwloc_obj_t hwloc_get_next_obj_covering_cpuset_by_depth(hwloc_topology_t topology, hwloc_const_cpuset_t set, int depth, hwloc_obj_t prev)
    Iterate through same-depth objects covering at least CPU set set.
    Definition: helper.h:348
    -
    hwloc_bitmap_set
    int hwloc_bitmap_set(hwloc_bitmap_t bitmap, unsigned id)
    Add index id in bitmap bitmap.
    -
    hwloc_bitmap_isset
    int hwloc_bitmap_isset(hwloc_const_bitmap_t bitmap, unsigned id)
    Test whether index id is part of bitmap bitmap.
    -
    hwloc_bitmap_or
    int hwloc_bitmap_or(hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
    Or bitmaps bitmap1 and bitmap2 and store the result in bitmap res.
    -
    hwloc_bitmap_zero
    void hwloc_bitmap_zero(hwloc_bitmap_t bitmap)
    Empty the bitmap bitmap.
    -
    hwloc_cpuset_from_linux_libnuma_ulongs
    static int hwloc_cpuset_from_linux_libnuma_ulongs(hwloc_topology_t topology, hwloc_cpuset_t cpuset, const unsigned long *mask, unsigned long maxnode)
    Convert the array of unsigned long mask into hwloc CPU set.
    Definition: linux-libnuma.h:131
    -
    hwloc_nodeset_to_linux_libnuma_ulongs
    static int hwloc_nodeset_to_linux_libnuma_ulongs(hwloc_topology_t topology, hwloc_const_nodeset_t nodeset, unsigned long *mask, unsigned long *maxnode)
    Convert hwloc NUMA node set nodeset into the array of unsigned long mask.
    Definition: linux-libnuma.h:93
    -
    hwloc_nodeset_from_linux_libnuma_ulongs
    static int hwloc_nodeset_from_linux_libnuma_ulongs(hwloc_topology_t topology, hwloc_nodeset_t nodeset, const unsigned long *mask, unsigned long maxnode)
    Convert the array of unsigned long mask into hwloc NUMA node set.
    Definition: linux-libnuma.h:158
    -
    hwloc_cpuset_to_linux_libnuma_ulongs
    static int hwloc_cpuset_to_linux_libnuma_ulongs(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, unsigned long *mask, unsigned long *maxnode)
    Convert hwloc CPU set cpuset into the array of unsigned long mask.
    Definition: linux-libnuma.h:57
    -
    hwloc_cpuset_from_linux_libnuma_bitmask
    static int hwloc_cpuset_from_linux_libnuma_bitmask(hwloc_topology_t topology, hwloc_cpuset_t cpuset, const struct bitmask *bitmask)
    Convert libnuma bitmask bitmask into hwloc CPU set cpuset.
    Definition: linux-libnuma.h:251
    -
    hwloc_nodeset_from_linux_libnuma_bitmask
    static int hwloc_nodeset_from_linux_libnuma_bitmask(hwloc_topology_t topology, hwloc_nodeset_t nodeset, const struct bitmask *bitmask)
    Convert libnuma bitmask bitmask into hwloc NUMA node set nodeset.
    Definition: linux-libnuma.h:273
    -
    hwloc_cpuset_to_linux_libnuma_bitmask
    static struct bitmask * hwloc_cpuset_to_linux_libnuma_bitmask(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset)
    Convert hwloc CPU set cpuset into the returned libnuma bitmask.
    Definition: linux-libnuma.h:204
    -
    hwloc_nodeset_to_linux_libnuma_bitmask
    static struct bitmask * hwloc_nodeset_to_linux_libnuma_bitmask(hwloc_topology_t topology, hwloc_const_nodeset_t nodeset)
    Convert hwloc NUMA node set nodeset into the returned libnuma bitmask.
    Definition: linux-libnuma.h:229
    -
    hwloc_obj
    Structure of a topology object.
    Definition: hwloc.h:420
    -
    hwloc_obj::os_index
    unsigned os_index
    OS-provided physical index number. It is not guaranteed unique across the entire machine,...
    Definition: hwloc.h:425
    -
    hwloc_obj::cpuset
    hwloc_cpuset_t cpuset
    CPUs covered by this object.
    Definition: hwloc.h:536
    -
    hwloc_obj::attr
    union hwloc_obj_attr_u * attr
    Object type-specific Attributes, may be NULL if no attribute value was found.
    Definition: hwloc.h:439
    -
    hwloc_obj_attr_u::numanode
    struct hwloc_obj_attr_u::hwloc_numanode_attr_s numanode
    -
    hwloc_obj_attr_u::hwloc_numanode_attr_s::local_memory
    hwloc_uint64_t local_memory
    Local memory (in bytes)
    Definition: hwloc.h:626
    -
    - - - - - - - - -
    -
    windows.h
    -
    -
    -
    1/*
    -
    2 * Copyright © 2021 Inria. All rights reserved.
    -
    3 * See COPYING in top-level directory.
    -
    4 */
    -
    5
    -
    13#ifndef HWLOC_WINDOWS_H
    -
    14#define HWLOC_WINDOWS_H
    -
    15
    -
    16#include "hwloc.h"
    -
    17
    -
    18
    -
    19#ifdef __cplusplus
    -
    20extern "C" {
    -
    21#endif
    -
    22
    -
    23
    -
    50HWLOC_DECLSPEC int hwloc_windows_get_nr_processor_groups(hwloc_topology_t topology, unsigned long flags);
    -
    51
    -
    66HWLOC_DECLSPEC int hwloc_windows_get_processor_group_cpuset(hwloc_topology_t topology, unsigned pg_index, hwloc_cpuset_t cpuset, unsigned long flags);
    -
    67
    -
    71#ifdef __cplusplus
    -
    72} /* extern "C" */
    -
    73#endif
    -
    74
    -
    75
    -
    76#endif /* HWLOC_WINDOWS_H */
    -
    hwloc_cpuset_t
    hwloc_bitmap_t hwloc_cpuset_t
    A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
    Definition: hwloc.h:161
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:716
    -
    hwloc_windows_get_processor_group_cpuset
    int hwloc_windows_get_processor_group_cpuset(hwloc_topology_t topology, unsigned pg_index, hwloc_cpuset_t cpuset, unsigned long flags)
    Get the CPU-set of a Windows processor group.
    -
    hwloc_windows_get_nr_processor_groups
    int hwloc_windows_get_nr_processor_groups(hwloc_topology_t topology, unsigned long flags)
    Get the number of Windows processor groups.
    -
    - - - - - - - - -
    -
    glibc-sched.h
    -
    -
    -
    1/*
    -
    2 * Copyright © 2009 CNRS
    -
    3 * Copyright © 2009-2023 Inria. All rights reserved.
    -
    4 * Copyright © 2009-2011 Université Bordeaux
    -
    5 * Copyright © 2011 Cisco Systems, Inc. All rights reserved.
    -
    6 * See COPYING in top-level directory.
    -
    7 */
    -
    8
    -
    17#ifndef HWLOC_GLIBC_SCHED_H
    -
    18#define HWLOC_GLIBC_SCHED_H
    -
    19
    -
    20#include "hwloc.h"
    -
    21#include "hwloc/helper.h"
    -
    22
    -
    23#include <assert.h>
    -
    24
    -
    25#if !defined _GNU_SOURCE || (!defined _SCHED_H && !defined _SCHED_H_) || (!defined CPU_SETSIZE && !defined sched_priority)
    -
    26#error Please make sure to include sched.h before including glibc-sched.h, and define _GNU_SOURCE before any inclusion of sched.h
    -
    27#endif
    -
    28
    -
    29
    -
    30#ifdef __cplusplus
    -
    31extern "C" {
    -
    32#endif
    -
    33
    -
    34
    -
    35#ifdef HWLOC_HAVE_CPU_SET
    -
    36
    -
    37
    -
    58static __hwloc_inline int
    -
    59hwloc_cpuset_to_glibc_sched_affinity(hwloc_topology_t topology __hwloc_attribute_unused, hwloc_const_cpuset_t hwlocset,
    -
    60 cpu_set_t *schedset, size_t schedsetsize)
    -
    61{
    -
    62#ifdef CPU_ZERO_S
    -
    63 unsigned cpu;
    -
    64 CPU_ZERO_S(schedsetsize, schedset);
    -
    65 hwloc_bitmap_foreach_begin(cpu, hwlocset)
    -
    66 CPU_SET_S(cpu, schedsetsize, schedset);
    -
    67 hwloc_bitmap_foreach_end();
    -
    68#else /* !CPU_ZERO_S */
    -
    69 unsigned cpu;
    -
    70 CPU_ZERO(schedset);
    -
    71 assert(schedsetsize == sizeof(cpu_set_t));
    -
    72 hwloc_bitmap_foreach_begin(cpu, hwlocset)
    -
    73 CPU_SET(cpu, schedset);
    -
    74 hwloc_bitmap_foreach_end();
    -
    75#endif /* !CPU_ZERO_S */
    -
    76 return 0;
    -
    77}
    -
    78
    -
    89static __hwloc_inline int
    -
    90hwloc_cpuset_from_glibc_sched_affinity(hwloc_topology_t topology __hwloc_attribute_unused, hwloc_cpuset_t hwlocset,
    -
    91 const cpu_set_t *schedset, size_t schedsetsize)
    -
    92{
    -
    93 int cpu;
    -
    94#ifdef CPU_ZERO_S
    -
    95 int count;
    -
    96#endif
    -
    97 hwloc_bitmap_zero(hwlocset);
    -
    98#ifdef CPU_ZERO_S
    -
    99 count = CPU_COUNT_S(schedsetsize, schedset);
    -
    100 cpu = 0;
    -
    101 while (count) {
    -
    102 if (CPU_ISSET_S(cpu, schedsetsize, schedset)) {
    -
    103 if (hwloc_bitmap_set(hwlocset, cpu) < 0)
    -
    104 return -1;
    -
    105 count--;
    -
    106 }
    -
    107 cpu++;
    -
    108 }
    -
    109#else /* !CPU_ZERO_S */
    -
    110 /* sched.h does not support dynamic cpu_set_t (introduced in glibc 2.7),
    -
    111 * assume we have a very old interface without CPU_COUNT (added in 2.6)
    -
    112 */
    -
    113 assert(schedsetsize == sizeof(cpu_set_t));
    -
    114 for(cpu=0; cpu<CPU_SETSIZE; cpu++)
    -
    115 if (CPU_ISSET(cpu, schedset))
    -
    116 if (hwloc_bitmap_set(hwlocset, cpu) < 0)
    -
    117 return -1;
    -
    118#endif /* !CPU_ZERO_S */
    -
    119 return 0;
    -
    120}
    -
    121
    -
    125#endif /* CPU_SET */
    -
    126
    -
    127
    -
    128#ifdef __cplusplus
    -
    129} /* extern "C" */
    -
    130#endif
    -
    131
    -
    132
    -
    133#endif /* HWLOC_GLIBC_SCHED_H */
    -
    hwloc_const_cpuset_t
    hwloc_const_bitmap_t hwloc_const_cpuset_t
    A non-modifiable hwloc_cpuset_t.
    Definition: hwloc.h:163
    -
    hwloc_cpuset_t
    hwloc_bitmap_t hwloc_cpuset_t
    A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
    Definition: hwloc.h:161
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:716
    -
    hwloc_bitmap_set
    int hwloc_bitmap_set(hwloc_bitmap_t bitmap, unsigned id)
    Add index id in bitmap bitmap.
    -
    hwloc_bitmap_foreach_begin
    #define hwloc_bitmap_foreach_begin(id, bitmap)
    Loop macro iterating on bitmap bitmap.
    Definition: bitmap.h:387
    -
    hwloc_bitmap_zero
    void hwloc_bitmap_zero(hwloc_bitmap_t bitmap)
    Empty the bitmap bitmap.
    -
    hwloc_bitmap_foreach_end
    #define hwloc_bitmap_foreach_end()
    End of loop macro iterating on a bitmap.
    Definition: bitmap.h:401
    -
    hwloc_cpuset_to_glibc_sched_affinity
    static int hwloc_cpuset_to_glibc_sched_affinity(hwloc_topology_t topology, hwloc_const_cpuset_t hwlocset, cpu_set_t *schedset, size_t schedsetsize)
    Convert hwloc CPU set toposet into glibc sched affinity CPU set schedset.
    Definition: glibc-sched.h:59
    -
    hwloc_cpuset_from_glibc_sched_affinity
    static int hwloc_cpuset_from_glibc_sched_affinity(hwloc_topology_t topology, hwloc_cpuset_t hwlocset, const cpu_set_t *schedset, size_t schedsetsize)
    Convert glibc sched affinity CPU set schedset into hwloc CPU set.
    Definition: glibc-sched.h:90
    -
    - - - - - - - - -
    -
    opencl.h
    -
    -
    -
    1/*
    -
    2 * Copyright © 2012-2023 Inria. All rights reserved.
    -
    3 * Copyright © 2013, 2018 Université Bordeaux. All right reserved.
    -
    4 * See COPYING in top-level directory.
    -
    5 */
    -
    6
    -
    14#ifndef HWLOC_OPENCL_H
    -
    15#define HWLOC_OPENCL_H
    -
    16
    -
    17#include "hwloc.h"
    -
    18#include "hwloc/autogen/config.h"
    -
    19#include "hwloc/helper.h"
    -
    20#ifdef HWLOC_LINUX_SYS
    -
    21#include "hwloc/linux.h"
    -
    22#endif
    -
    23
    -
    24#ifdef __APPLE__
    -
    25#include <OpenCL/cl.h>
    -
    26#else
    -
    27#include <CL/cl.h>
    -
    28#endif
    -
    29
    -
    30#include <stdio.h>
    -
    31
    -
    32
    -
    33#ifdef __cplusplus
    -
    34extern "C" {
    -
    35#endif
    -
    36
    -
    37
    -
    38/* OpenCL extensions aren't always shipped with default headers, and
    -
    39 * they don't always reflect what the installed implementations support.
    -
    40 * Try everything and let the implementation return errors when non supported.
    -
    41 */
    -
    42/* Copyright (c) 2008-2018 The Khronos Group Inc. */
    -
    43
    -
    44/* needs "cl_amd_device_attribute_query" device extension, but not strictly required for clGetDeviceInfo() */
    -
    45#define HWLOC_CL_DEVICE_TOPOLOGY_AMD 0x4037
    -
    46typedef union {
    -
    47 struct { cl_uint type; cl_uint data[5]; } raw;
    -
    48 struct { cl_uint type; cl_char unused[17]; cl_char bus; cl_char device; cl_char function; } pcie;
    -
    49} hwloc_cl_device_topology_amd;
    -
    50#define HWLOC_CL_DEVICE_TOPOLOGY_TYPE_PCIE_AMD 1
    -
    51
    -
    52/* needs "cl_nv_device_attribute_query" device extension, but not strictly required for clGetDeviceInfo() */
    -
    53#define HWLOC_CL_DEVICE_PCI_BUS_ID_NV 0x4008
    -
    54#define HWLOC_CL_DEVICE_PCI_SLOT_ID_NV 0x4009
    -
    55#define HWLOC_CL_DEVICE_PCI_DOMAIN_ID_NV 0x400A
    -
    56
    -
    57
    -
    76static __hwloc_inline int
    -
    77hwloc_opencl_get_device_pci_busid(cl_device_id device,
    -
    78 unsigned *domain, unsigned *bus, unsigned *dev, unsigned *func)
    -
    79{
    -
    80 hwloc_cl_device_topology_amd amdtopo;
    -
    81 cl_uint nvbus, nvslot, nvdomain;
    -
    82 cl_int clret;
    -
    83
    -
    84 clret = clGetDeviceInfo(device, HWLOC_CL_DEVICE_TOPOLOGY_AMD, sizeof(amdtopo), &amdtopo, NULL);
    -
    85 if (CL_SUCCESS == clret
    -
    86 && HWLOC_CL_DEVICE_TOPOLOGY_TYPE_PCIE_AMD == amdtopo.raw.type) {
    -
    87 *domain = 0; /* can't do anything better */
    -
    88 /* cl_device_topology_amd stores bus ID in cl_char, dont convert those signed char directly to unsigned int */
    -
    89 *bus = (unsigned) (unsigned char) amdtopo.pcie.bus;
    -
    90 *dev = (unsigned) (unsigned char) amdtopo.pcie.device;
    -
    91 *func = (unsigned) (unsigned char) amdtopo.pcie.function;
    -
    92 return 0;
    -
    93 }
    -
    94
    -
    95 clret = clGetDeviceInfo(device, HWLOC_CL_DEVICE_PCI_BUS_ID_NV, sizeof(nvbus), &nvbus, NULL);
    -
    96 if (CL_SUCCESS == clret) {
    -
    97 clret = clGetDeviceInfo(device, HWLOC_CL_DEVICE_PCI_SLOT_ID_NV, sizeof(nvslot), &nvslot, NULL);
    -
    98 if (CL_SUCCESS == clret) {
    -
    99 clret = clGetDeviceInfo(device, HWLOC_CL_DEVICE_PCI_DOMAIN_ID_NV, sizeof(nvdomain), &nvdomain, NULL);
    -
    100 if (CL_SUCCESS == clret) { /* available since CUDA 10.2 */
    -
    101 *domain = nvdomain;
    -
    102 } else {
    -
    103 *domain = 0;
    -
    104 }
    -
    105 *bus = nvbus & 0xff;
    -
    106 /* non-documented but used in many other projects */
    -
    107 *dev = nvslot >> 3;
    -
    108 *func = nvslot & 0x7;
    -
    109 return 0;
    -
    110 }
    -
    111 }
    -
    112
    -
    113 return -1;
    -
    114}
    -
    115
    -
    136static __hwloc_inline int
    -
    137hwloc_opencl_get_device_cpuset(hwloc_topology_t topology __hwloc_attribute_unused,
    -
    138 cl_device_id device __hwloc_attribute_unused,
    -
    139 hwloc_cpuset_t set)
    -
    140{
    -
    141#if (defined HWLOC_LINUX_SYS)
    -
    142 /* If we're on Linux, try AMD/NVIDIA extensions + the sysfs mechanism to get the local cpus */
    -
    143#define HWLOC_OPENCL_DEVICE_SYSFS_PATH_MAX 128
    -
    144 char path[HWLOC_OPENCL_DEVICE_SYSFS_PATH_MAX];
    -
    145 unsigned pcidomain, pcibus, pcidev, pcifunc;
    -
    146
    -
    147 if (!hwloc_topology_is_thissystem(topology)) {
    -
    148 errno = EINVAL;
    -
    149 return -1;
    -
    150 }
    -
    151
    -
    152 if (hwloc_opencl_get_device_pci_busid(device, &pcidomain, &pcibus, &pcidev, &pcifunc) < 0) {
    -
    153 hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
    -
    154 return 0;
    -
    155 }
    -
    156
    -
    157 sprintf(path, "/sys/bus/pci/devices/%04x:%02x:%02x.%01x/local_cpus", pcidomain, pcibus, pcidev, pcifunc);
    -
    158 if (hwloc_linux_read_path_as_cpumask(path, set) < 0
    -
    159 || hwloc_bitmap_iszero(set))
    -
    160 hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
    -
    161#else
    -
    162 /* Non-Linux systems simply get a full cpuset */
    -
    163 hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
    -
    164#endif
    -
    165 return 0;
    -
    166}
    -
    167
    -
    183static __hwloc_inline hwloc_obj_t
    -
    184hwloc_opencl_get_device_osdev_by_index(hwloc_topology_t topology,
    -
    185 unsigned platform_index, unsigned device_index)
    -
    186{
    -
    187 unsigned x = (unsigned) -1, y = (unsigned) -1;
    -
    188 hwloc_obj_t osdev = NULL;
    -
    189 while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
    -
    190 if (HWLOC_OBJ_OSDEV_COPROC == osdev->attr->osdev.type
    -
    191 && osdev->name
    -
    192 && sscanf(osdev->name, "opencl%ud%u", &x, &y) == 2
    -
    193 && platform_index == x && device_index == y)
    -
    194 return osdev;
    -
    195 }
    -
    196 return NULL;
    -
    197}
    -
    198
    -
    220static __hwloc_inline hwloc_obj_t
    -
    221hwloc_opencl_get_device_osdev(hwloc_topology_t topology __hwloc_attribute_unused,
    -
    222 cl_device_id device __hwloc_attribute_unused)
    -
    223{
    -
    224 hwloc_obj_t osdev;
    -
    225 unsigned pcidomain, pcibus, pcidevice, pcifunc;
    -
    226
    -
    227 if (hwloc_opencl_get_device_pci_busid(device, &pcidomain, &pcibus, &pcidevice, &pcifunc) < 0) {
    -
    228 errno = EINVAL;
    -
    229 return NULL;
    -
    230 }
    -
    231
    -
    232 osdev = NULL;
    -
    233 while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
    -
    234 hwloc_obj_t pcidev = osdev->parent;
    -
    235 if (strncmp(osdev->name, "opencl", 6))
    -
    236 continue;
    -
    237 if (pcidev
    -
    238 && pcidev->type == HWLOC_OBJ_PCI_DEVICE
    -
    239 && pcidev->attr->pcidev.domain == pcidomain
    -
    240 && pcidev->attr->pcidev.bus == pcibus
    -
    241 && pcidev->attr->pcidev.dev == pcidevice
    -
    242 && pcidev->attr->pcidev.func == pcifunc)
    -
    243 return osdev;
    -
    244 /* if PCI are filtered out, we need a info attr to match on */
    -
    245 }
    -
    246
    -
    247 return NULL;
    -
    248}
    -
    249
    -
    253#ifdef __cplusplus
    -
    254} /* extern "C" */
    -
    255#endif
    -
    256
    -
    257
    -
    258#endif /* HWLOC_OPENCL_H */
    -
    hwloc_cpuset_t
    hwloc_bitmap_t hwloc_cpuset_t
    A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
    Definition: hwloc.h:161
    -
    HWLOC_OBJ_OSDEV_COPROC
    @ HWLOC_OBJ_OSDEV_COPROC
    Operating system co-processor device. For instance "opencl0d0" for a OpenCL device,...
    Definition: hwloc.h:374
    -
    HWLOC_OBJ_PCI_DEVICE
    @ HWLOC_OBJ_PCI_DEVICE
    PCI device (filtered out by default).
    Definition: hwloc.h:290
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:716
    -
    hwloc_topology_is_thissystem
    int hwloc_topology_is_thissystem(hwloc_topology_t restrict topology)
    Does the topology context come from this system?
    -
    hwloc_topology_get_complete_cpuset
    hwloc_const_cpuset_t hwloc_topology_get_complete_cpuset(hwloc_topology_t topology)
    Get complete CPU set.
    -
    hwloc_get_next_osdev
    static hwloc_obj_t hwloc_get_next_osdev(hwloc_topology_t topology, hwloc_obj_t prev)
    Get the next OS device in the system.
    Definition: helper.h:1280
    -
    hwloc_bitmap_iszero
    int hwloc_bitmap_iszero(hwloc_const_bitmap_t bitmap)
    Test whether bitmap bitmap is empty.
    -
    hwloc_bitmap_copy
    int hwloc_bitmap_copy(hwloc_bitmap_t dst, hwloc_const_bitmap_t src)
    Copy the contents of bitmap src into the already allocated bitmap dst.
    -
    hwloc_linux_read_path_as_cpumask
    int hwloc_linux_read_path_as_cpumask(const char *path, hwloc_bitmap_t set)
    Convert a linux kernel cpumask file path into a hwloc bitmap set.
    -
    hwloc_opencl_get_device_pci_busid
    static int hwloc_opencl_get_device_pci_busid(cl_device_id device, unsigned *domain, unsigned *bus, unsigned *dev, unsigned *func)
    Return the domain, bus and device IDs of the OpenCL device device.
    Definition: opencl.h:77
    -
    hwloc_opencl_get_device_cpuset
    static int hwloc_opencl_get_device_cpuset(hwloc_topology_t topology, cl_device_id device, hwloc_cpuset_t set)
    Get the CPU set of processors that are physically close to OpenCL device device.
    Definition: opencl.h:137
    -
    hwloc_opencl_get_device_osdev
    static hwloc_obj_t hwloc_opencl_get_device_osdev(hwloc_topology_t topology, cl_device_id device)
    Get the hwloc OS device object corresponding to OpenCL device deviceX.
    Definition: opencl.h:221
    -
    hwloc_opencl_get_device_osdev_by_index
    static hwloc_obj_t hwloc_opencl_get_device_osdev_by_index(hwloc_topology_t topology, unsigned platform_index, unsigned device_index)
    Get the hwloc OS device object corresponding to the OpenCL device for the given indexes.
    Definition: opencl.h:184
    -
    hwloc_obj
    Structure of a topology object.
    Definition: hwloc.h:420
    -
    hwloc_obj::name
    char * name
    Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name str...
    Definition: hwloc.h:432
    -
    hwloc_obj::type
    hwloc_obj_type_t type
    Type of object.
    Definition: hwloc.h:422
    -
    hwloc_obj::attr
    union hwloc_obj_attr_u * attr
    Object type-specific Attributes, may be NULL if no attribute value was found.
    Definition: hwloc.h:439
    -
    hwloc_obj::parent
    struct hwloc_obj * parent
    Parent, NULL if root (Machine object)
    Definition: hwloc.h:470
    -
    hwloc_obj_attr_u::pcidev
    struct hwloc_obj_attr_u::hwloc_pcidev_attr_s pcidev
    -
    hwloc_obj_attr_u::osdev
    struct hwloc_obj_attr_u::hwloc_osdev_attr_s osdev
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::dev
    unsigned char dev
    Definition: hwloc.h:663
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::func
    unsigned char func
    Definition: hwloc.h:663
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::domain
    unsigned short domain
    Definition: hwloc.h:659
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::bus
    unsigned char bus
    Definition: hwloc.h:663
    -
    hwloc_obj_attr_u::hwloc_osdev_attr_s::type
    hwloc_obj_osdev_type_t type
    Definition: hwloc.h:690
    -
    hwloc_cl_device_topology_amd
    Definition: opencl.h:46
    -
    hwloc_cl_device_topology_amd::device
    cl_char device
    Definition: opencl.h:48
    -
    hwloc_cl_device_topology_amd::pcie
    struct hwloc_cl_device_topology_amd::@4 pcie
    -
    hwloc_cl_device_topology_amd::bus
    cl_char bus
    Definition: opencl.h:48
    -
    hwloc_cl_device_topology_amd::function
    cl_char function
    Definition: opencl.h:48
    -
    hwloc_cl_device_topology_amd::raw
    struct hwloc_cl_device_topology_amd::@3 raw
    -
    hwloc_cl_device_topology_amd::type
    cl_uint type
    Definition: opencl.h:47
    -
    - - - - - - - - -
    -
    cuda.h
    -
    -
    -
    1/*
    -
    2 * Copyright © 2010-2023 Inria. All rights reserved.
    -
    3 * Copyright © 2010-2011 Université Bordeaux
    -
    4 * Copyright © 2011 Cisco Systems, Inc. All rights reserved.
    -
    5 * See COPYING in top-level directory.
    -
    6 */
    -
    7
    -
    16#ifndef HWLOC_CUDA_H
    -
    17#define HWLOC_CUDA_H
    -
    18
    -
    19#include "hwloc.h"
    -
    20#include "hwloc/autogen/config.h"
    -
    21#include "hwloc/helper.h"
    -
    22#ifdef HWLOC_LINUX_SYS
    -
    23#include "hwloc/linux.h"
    -
    24#endif
    -
    25
    -
    26#include <cuda.h>
    -
    27
    -
    28
    -
    29#ifdef __cplusplus
    -
    30extern "C" {
    -
    31#endif
    -
    32
    -
    33
    -
    49static __hwloc_inline int
    -
    50hwloc_cuda_get_device_pci_ids(hwloc_topology_t topology __hwloc_attribute_unused,
    -
    51 CUdevice cudevice, int *domain, int *bus, int *dev)
    -
    52{
    -
    53 CUresult cres;
    -
    54
    -
    55#if CUDA_VERSION >= 4000
    -
    56 cres = cuDeviceGetAttribute(domain, CU_DEVICE_ATTRIBUTE_PCI_DOMAIN_ID, cudevice);
    -
    57 if (cres != CUDA_SUCCESS) {
    -
    58 errno = ENOSYS;
    -
    59 return -1;
    -
    60 }
    -
    61#else
    -
    62 *domain = 0;
    -
    63#endif
    -
    64 cres = cuDeviceGetAttribute(bus, CU_DEVICE_ATTRIBUTE_PCI_BUS_ID, cudevice);
    -
    65 if (cres != CUDA_SUCCESS) {
    -
    66 errno = ENOSYS;
    -
    67 return -1;
    -
    68 }
    -
    69 cres = cuDeviceGetAttribute(dev, CU_DEVICE_ATTRIBUTE_PCI_DEVICE_ID, cudevice);
    -
    70 if (cres != CUDA_SUCCESS) {
    -
    71 errno = ENOSYS;
    -
    72 return -1;
    -
    73 }
    -
    74
    -
    75 return 0;
    -
    76}
    -
    77
    -
    97static __hwloc_inline int
    -
    98hwloc_cuda_get_device_cpuset(hwloc_topology_t topology __hwloc_attribute_unused,
    -
    99 CUdevice cudevice, hwloc_cpuset_t set)
    -
    100{
    -
    101#ifdef HWLOC_LINUX_SYS
    -
    102 /* If we're on Linux, use the sysfs mechanism to get the local cpus */
    -
    103#define HWLOC_CUDA_DEVICE_SYSFS_PATH_MAX 128
    -
    104 char path[HWLOC_CUDA_DEVICE_SYSFS_PATH_MAX];
    -
    105 int domainid, busid, deviceid;
    -
    106
    -
    107 if (hwloc_cuda_get_device_pci_ids(topology, cudevice, &domainid, &busid, &deviceid))
    -
    108 return -1;
    -
    109
    -
    110 if (!hwloc_topology_is_thissystem(topology)) {
    -
    111 errno = EINVAL;
    -
    112 return -1;
    -
    113 }
    -
    114
    -
    115 sprintf(path, "/sys/bus/pci/devices/%04x:%02x:%02x.0/local_cpus", domainid, busid, deviceid);
    -
    116 if (hwloc_linux_read_path_as_cpumask(path, set) < 0
    -
    117 || hwloc_bitmap_iszero(set))
    -
    118 hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
    -
    119#else
    -
    120 /* Non-Linux systems simply get a full cpuset */
    -
    121 hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
    -
    122#endif
    -
    123 return 0;
    -
    124}
    -
    125
    -
    136static __hwloc_inline hwloc_obj_t
    -
    137hwloc_cuda_get_device_pcidev(hwloc_topology_t topology, CUdevice cudevice)
    -
    138{
    -
    139 int domain, bus, dev;
    -
    140
    -
    141 if (hwloc_cuda_get_device_pci_ids(topology, cudevice, &domain, &bus, &dev))
    -
    142 return NULL;
    -
    143
    -
    144 return hwloc_get_pcidev_by_busid(topology, domain, bus, dev, 0);
    -
    145}
    -
    146
    -
    162static __hwloc_inline hwloc_obj_t
    -
    163hwloc_cuda_get_device_osdev(hwloc_topology_t topology, CUdevice cudevice)
    -
    164{
    -
    165 hwloc_obj_t osdev = NULL;
    -
    166 int domain, bus, dev;
    -
    167
    -
    168 if (hwloc_cuda_get_device_pci_ids(topology, cudevice, &domain, &bus, &dev))
    -
    169 return NULL;
    -
    170
    -
    171 osdev = NULL;
    -
    172 while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
    -
    173 hwloc_obj_t pcidev = osdev->parent;
    -
    174 if (strncmp(osdev->name, "cuda", 4))
    -
    175 continue;
    -
    176 if (pcidev
    -
    177 && pcidev->type == HWLOC_OBJ_PCI_DEVICE
    -
    178 && (int) pcidev->attr->pcidev.domain == domain
    -
    179 && (int) pcidev->attr->pcidev.bus == bus
    -
    180 && (int) pcidev->attr->pcidev.dev == dev
    -
    181 && pcidev->attr->pcidev.func == 0)
    -
    182 return osdev;
    -
    183 /* if PCI are filtered out, we need a info attr to match on */
    -
    184 }
    -
    185
    -
    186 return NULL;
    -
    187}
    -
    188
    -
    204static __hwloc_inline hwloc_obj_t
    -
    205hwloc_cuda_get_device_osdev_by_index(hwloc_topology_t topology, unsigned idx)
    -
    206{
    -
    207 hwloc_obj_t osdev = NULL;
    -
    208 while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
    -
    209 if (HWLOC_OBJ_OSDEV_COPROC == osdev->attr->osdev.type
    -
    210 && osdev->name
    -
    211 && !strncmp("cuda", osdev->name, 4)
    -
    212 && atoi(osdev->name + 4) == (int) idx)
    -
    213 return osdev;
    -
    214 }
    -
    215 return NULL;
    -
    216}
    -
    217
    -
    221#ifdef __cplusplus
    -
    222} /* extern "C" */
    -
    223#endif
    -
    224
    -
    225
    -
    226#endif /* HWLOC_CUDA_H */
    -
    hwloc_cpuset_t
    hwloc_bitmap_t hwloc_cpuset_t
    A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
    Definition: hwloc.h:161
    -
    HWLOC_OBJ_OSDEV_COPROC
    @ HWLOC_OBJ_OSDEV_COPROC
    Operating system co-processor device. For instance "opencl0d0" for a OpenCL device,...
    Definition: hwloc.h:374
    -
    HWLOC_OBJ_PCI_DEVICE
    @ HWLOC_OBJ_PCI_DEVICE
    PCI device (filtered out by default).
    Definition: hwloc.h:290
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:716
    -
    hwloc_topology_is_thissystem
    int hwloc_topology_is_thissystem(hwloc_topology_t restrict topology)
    Does the topology context come from this system?
    -
    hwloc_topology_get_complete_cpuset
    hwloc_const_cpuset_t hwloc_topology_get_complete_cpuset(hwloc_topology_t topology)
    Get complete CPU set.
    -
    hwloc_get_next_osdev
    static hwloc_obj_t hwloc_get_next_osdev(hwloc_topology_t topology, hwloc_obj_t prev)
    Get the next OS device in the system.
    Definition: helper.h:1280
    -
    hwloc_get_pcidev_by_busid
    static hwloc_obj_t hwloc_get_pcidev_by_busid(hwloc_topology_t topology, unsigned domain, unsigned bus, unsigned dev, unsigned func)
    Find the PCI device object matching the PCI bus id given domain, bus device and function PCI bus id.
    Definition: helper.h:1239
    -
    hwloc_bitmap_iszero
    int hwloc_bitmap_iszero(hwloc_const_bitmap_t bitmap)
    Test whether bitmap bitmap is empty.
    -
    hwloc_bitmap_copy
    int hwloc_bitmap_copy(hwloc_bitmap_t dst, hwloc_const_bitmap_t src)
    Copy the contents of bitmap src into the already allocated bitmap dst.
    -
    hwloc_linux_read_path_as_cpumask
    int hwloc_linux_read_path_as_cpumask(const char *path, hwloc_bitmap_t set)
    Convert a linux kernel cpumask file path into a hwloc bitmap set.
    -
    hwloc_cuda_get_device_pci_ids
    static int hwloc_cuda_get_device_pci_ids(hwloc_topology_t topology, CUdevice cudevice, int *domain, int *bus, int *dev)
    Return the domain, bus and device IDs of the CUDA device cudevice.
    Definition: cuda.h:50
    -
    hwloc_cuda_get_device_pcidev
    static hwloc_obj_t hwloc_cuda_get_device_pcidev(hwloc_topology_t topology, CUdevice cudevice)
    Get the hwloc PCI device object corresponding to the CUDA device cudevice.
    Definition: cuda.h:137
    -
    hwloc_cuda_get_device_osdev_by_index
    static hwloc_obj_t hwloc_cuda_get_device_osdev_by_index(hwloc_topology_t topology, unsigned idx)
    Get the hwloc OS device object corresponding to the CUDA device whose index is idx.
    Definition: cuda.h:205
    -
    hwloc_cuda_get_device_osdev
    static hwloc_obj_t hwloc_cuda_get_device_osdev(hwloc_topology_t topology, CUdevice cudevice)
    Get the hwloc OS device object corresponding to CUDA device cudevice.
    Definition: cuda.h:163
    -
    hwloc_cuda_get_device_cpuset
    static int hwloc_cuda_get_device_cpuset(hwloc_topology_t topology, CUdevice cudevice, hwloc_cpuset_t set)
    Get the CPU set of processors that are physically close to device cudevice.
    Definition: cuda.h:98
    -
    hwloc_obj
    Structure of a topology object.
    Definition: hwloc.h:420
    -
    hwloc_obj::name
    char * name
    Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name str...
    Definition: hwloc.h:432
    -
    hwloc_obj::type
    hwloc_obj_type_t type
    Type of object.
    Definition: hwloc.h:422
    -
    hwloc_obj::attr
    union hwloc_obj_attr_u * attr
    Object type-specific Attributes, may be NULL if no attribute value was found.
    Definition: hwloc.h:439
    -
    hwloc_obj::parent
    struct hwloc_obj * parent
    Parent, NULL if root (Machine object)
    Definition: hwloc.h:470
    -
    hwloc_obj_attr_u::pcidev
    struct hwloc_obj_attr_u::hwloc_pcidev_attr_s pcidev
    -
    hwloc_obj_attr_u::osdev
    struct hwloc_obj_attr_u::hwloc_osdev_attr_s osdev
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::dev
    unsigned char dev
    Definition: hwloc.h:663
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::func
    unsigned char func
    Definition: hwloc.h:663
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::domain
    unsigned short domain
    Definition: hwloc.h:659
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::bus
    unsigned char bus
    Definition: hwloc.h:663
    -
    hwloc_obj_attr_u::hwloc_osdev_attr_s::type
    hwloc_obj_osdev_type_t type
    Definition: hwloc.h:690
    -
    - - - - - - - - -
    -
    cudart.h
    -
    -
    -
    1/*
    -
    2 * Copyright © 2010-2023 Inria. All rights reserved.
    -
    3 * Copyright © 2010-2011 Université Bordeaux
    -
    4 * Copyright © 2011 Cisco Systems, Inc. All rights reserved.
    -
    5 * See COPYING in top-level directory.
    -
    6 */
    -
    7
    -
    16#ifndef HWLOC_CUDART_H
    -
    17#define HWLOC_CUDART_H
    -
    18
    -
    19#include "hwloc.h"
    -
    20#include "hwloc/autogen/config.h"
    -
    21#include "hwloc/helper.h"
    -
    22#ifdef HWLOC_LINUX_SYS
    -
    23#include "hwloc/linux.h"
    -
    24#endif
    -
    25
    -
    26#include <cuda.h> /* for CUDA_VERSION */
    -
    27#include <cuda_runtime_api.h>
    -
    28
    -
    29
    -
    30#ifdef __cplusplus
    -
    31extern "C" {
    -
    32#endif
    -
    33
    -
    34
    -
    50static __hwloc_inline int
    -
    51hwloc_cudart_get_device_pci_ids(hwloc_topology_t topology __hwloc_attribute_unused,
    -
    52 int idx, int *domain, int *bus, int *dev)
    -
    53{
    -
    54 cudaError_t cerr;
    -
    55 struct cudaDeviceProp prop;
    -
    56
    -
    57 cerr = cudaGetDeviceProperties(&prop, idx);
    -
    58 if (cerr) {
    -
    59 errno = ENOSYS;
    -
    60 return -1;
    -
    61 }
    -
    62
    -
    63#if CUDA_VERSION >= 4000
    -
    64 *domain = prop.pciDomainID;
    -
    65#else
    -
    66 *domain = 0;
    -
    67#endif
    -
    68
    -
    69 *bus = prop.pciBusID;
    -
    70 *dev = prop.pciDeviceID;
    -
    71
    -
    72 return 0;
    -
    73}
    -
    74
    -
    94static __hwloc_inline int
    -
    95hwloc_cudart_get_device_cpuset(hwloc_topology_t topology __hwloc_attribute_unused,
    -
    96 int idx, hwloc_cpuset_t set)
    -
    97{
    -
    98#ifdef HWLOC_LINUX_SYS
    -
    99 /* If we're on Linux, use the sysfs mechanism to get the local cpus */
    -
    100#define HWLOC_CUDART_DEVICE_SYSFS_PATH_MAX 128
    -
    101 char path[HWLOC_CUDART_DEVICE_SYSFS_PATH_MAX];
    -
    102 int domain, bus, dev;
    -
    103
    -
    104 if (hwloc_cudart_get_device_pci_ids(topology, idx, &domain, &bus, &dev))
    -
    105 return -1;
    -
    106
    -
    107 if (!hwloc_topology_is_thissystem(topology)) {
    -
    108 errno = EINVAL;
    -
    109 return -1;
    -
    110 }
    -
    111
    -
    112 sprintf(path, "/sys/bus/pci/devices/%04x:%02x:%02x.0/local_cpus", (unsigned) domain, (unsigned) bus, (unsigned) dev);
    -
    113 if (hwloc_linux_read_path_as_cpumask(path, set) < 0
    -
    114 || hwloc_bitmap_iszero(set))
    -
    115 hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
    -
    116#else
    -
    117 /* Non-Linux systems simply get a full cpuset */
    -
    118 hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
    -
    119#endif
    -
    120 return 0;
    -
    121}
    -
    122
    -
    133static __hwloc_inline hwloc_obj_t
    -
    134hwloc_cudart_get_device_pcidev(hwloc_topology_t topology, int idx)
    -
    135{
    -
    136 int domain, bus, dev;
    -
    137
    -
    138 if (hwloc_cudart_get_device_pci_ids(topology, idx, &domain, &bus, &dev))
    -
    139 return NULL;
    -
    140
    -
    141 return hwloc_get_pcidev_by_busid(topology, domain, bus, dev, 0);
    -
    142}
    -
    143
    -
    161static __hwloc_inline hwloc_obj_t
    -
    162hwloc_cudart_get_device_osdev_by_index(hwloc_topology_t topology, unsigned idx)
    -
    163{
    -
    164 hwloc_obj_t osdev = NULL;
    -
    165 while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
    -
    166 if (HWLOC_OBJ_OSDEV_COPROC == osdev->attr->osdev.type
    -
    167 && osdev->name
    -
    168 && !strncmp("cuda", osdev->name, 4)
    -
    169 && atoi(osdev->name + 4) == (int) idx)
    -
    170 return osdev;
    -
    171 }
    -
    172 return NULL;
    -
    173}
    -
    174
    -
    178#ifdef __cplusplus
    -
    179} /* extern "C" */
    -
    180#endif
    -
    181
    -
    182
    -
    183#endif /* HWLOC_CUDART_H */
    -
    hwloc_cpuset_t
    hwloc_bitmap_t hwloc_cpuset_t
    A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
    Definition: hwloc.h:161
    -
    HWLOC_OBJ_OSDEV_COPROC
    @ HWLOC_OBJ_OSDEV_COPROC
    Operating system co-processor device. For instance "opencl0d0" for a OpenCL device,...
    Definition: hwloc.h:374
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:716
    -
    hwloc_topology_is_thissystem
    int hwloc_topology_is_thissystem(hwloc_topology_t restrict topology)
    Does the topology context come from this system?
    -
    hwloc_topology_get_complete_cpuset
    hwloc_const_cpuset_t hwloc_topology_get_complete_cpuset(hwloc_topology_t topology)
    Get complete CPU set.
    -
    hwloc_get_next_osdev
    static hwloc_obj_t hwloc_get_next_osdev(hwloc_topology_t topology, hwloc_obj_t prev)
    Get the next OS device in the system.
    Definition: helper.h:1280
    -
    hwloc_get_pcidev_by_busid
    static hwloc_obj_t hwloc_get_pcidev_by_busid(hwloc_topology_t topology, unsigned domain, unsigned bus, unsigned dev, unsigned func)
    Find the PCI device object matching the PCI bus id given domain, bus device and function PCI bus id.
    Definition: helper.h:1239
    -
    hwloc_bitmap_iszero
    int hwloc_bitmap_iszero(hwloc_const_bitmap_t bitmap)
    Test whether bitmap bitmap is empty.
    -
    hwloc_bitmap_copy
    int hwloc_bitmap_copy(hwloc_bitmap_t dst, hwloc_const_bitmap_t src)
    Copy the contents of bitmap src into the already allocated bitmap dst.
    -
    hwloc_linux_read_path_as_cpumask
    int hwloc_linux_read_path_as_cpumask(const char *path, hwloc_bitmap_t set)
    Convert a linux kernel cpumask file path into a hwloc bitmap set.
    -
    hwloc_cudart_get_device_cpuset
    static int hwloc_cudart_get_device_cpuset(hwloc_topology_t topology, int idx, hwloc_cpuset_t set)
    Get the CPU set of processors that are physically close to device idx.
    Definition: cudart.h:95
    -
    hwloc_cudart_get_device_osdev_by_index
    static hwloc_obj_t hwloc_cudart_get_device_osdev_by_index(hwloc_topology_t topology, unsigned idx)
    Get the hwloc OS device object corresponding to the CUDA device whose index is idx.
    Definition: cudart.h:162
    -
    hwloc_cudart_get_device_pci_ids
    static int hwloc_cudart_get_device_pci_ids(hwloc_topology_t topology, int idx, int *domain, int *bus, int *dev)
    Return the domain, bus and device IDs of the CUDA device whose index is idx.
    Definition: cudart.h:51
    -
    hwloc_cudart_get_device_pcidev
    static hwloc_obj_t hwloc_cudart_get_device_pcidev(hwloc_topology_t topology, int idx)
    Get the hwloc PCI device object corresponding to the CUDA device whose index is idx.
    Definition: cudart.h:134
    -
    hwloc_obj
    Structure of a topology object.
    Definition: hwloc.h:420
    -
    hwloc_obj::name
    char * name
    Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name str...
    Definition: hwloc.h:432
    -
    hwloc_obj::attr
    union hwloc_obj_attr_u * attr
    Object type-specific Attributes, may be NULL if no attribute value was found.
    Definition: hwloc.h:439
    -
    hwloc_obj_attr_u::osdev
    struct hwloc_obj_attr_u::hwloc_osdev_attr_s osdev
    -
    hwloc_obj_attr_u::hwloc_osdev_attr_s::type
    hwloc_obj_osdev_type_t type
    Definition: hwloc.h:690
    -
    - - - - - - - - -
    -
    nvml.h
    -
    -
    -
    1/*
    -
    2 * Copyright © 2012-2023 Inria. All rights reserved.
    -
    3 * See COPYING in top-level directory.
    -
    4 */
    -
    5
    -
    13#ifndef HWLOC_NVML_H
    -
    14#define HWLOC_NVML_H
    -
    15
    -
    16#include "hwloc.h"
    -
    17#include "hwloc/autogen/config.h"
    -
    18#include "hwloc/helper.h"
    -
    19#ifdef HWLOC_LINUX_SYS
    -
    20#include "hwloc/linux.h"
    -
    21#endif
    -
    22
    -
    23#include <nvml.h>
    -
    24
    -
    25
    -
    26#ifdef __cplusplus
    -
    27extern "C" {
    -
    28#endif
    -
    29
    -
    30
    -
    58static __hwloc_inline int
    -
    59hwloc_nvml_get_device_cpuset(hwloc_topology_t topology __hwloc_attribute_unused,
    -
    60 nvmlDevice_t device, hwloc_cpuset_t set)
    -
    61{
    -
    62#ifdef HWLOC_LINUX_SYS
    -
    63 /* If we're on Linux, use the sysfs mechanism to get the local cpus */
    -
    64#define HWLOC_NVML_DEVICE_SYSFS_PATH_MAX 128
    -
    65 char path[HWLOC_NVML_DEVICE_SYSFS_PATH_MAX];
    -
    66 nvmlReturn_t nvres;
    -
    67 nvmlPciInfo_t pci;
    -
    68
    -
    69 if (!hwloc_topology_is_thissystem(topology)) {
    -
    70 errno = EINVAL;
    -
    71 return -1;
    -
    72 }
    -
    73
    -
    74 nvres = nvmlDeviceGetPciInfo(device, &pci);
    -
    75 if (NVML_SUCCESS != nvres) {
    -
    76 errno = EINVAL;
    -
    77 return -1;
    -
    78 }
    -
    79
    -
    80 sprintf(path, "/sys/bus/pci/devices/%04x:%02x:%02x.0/local_cpus", pci.domain, pci.bus, pci.device);
    -
    81 if (hwloc_linux_read_path_as_cpumask(path, set) < 0
    -
    82 || hwloc_bitmap_iszero(set))
    -
    83 hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
    -
    84#else
    -
    85 /* Non-Linux systems simply get a full cpuset */
    -
    86 hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
    -
    87#endif
    -
    88 return 0;
    -
    89}
    -
    90
    -
    104static __hwloc_inline hwloc_obj_t
    -
    105hwloc_nvml_get_device_osdev_by_index(hwloc_topology_t topology, unsigned idx)
    -
    106{
    -
    107 hwloc_obj_t osdev = NULL;
    -
    108 while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
    -
    109 if (HWLOC_OBJ_OSDEV_GPU == osdev->attr->osdev.type
    -
    110 && osdev->name
    -
    111 && !strncmp("nvml", osdev->name, 4)
    -
    112 && atoi(osdev->name + 4) == (int) idx)
    -
    113 return osdev;
    -
    114 }
    -
    115 return NULL;
    -
    116}
    -
    117
    -
    131static __hwloc_inline hwloc_obj_t
    -
    132hwloc_nvml_get_device_osdev(hwloc_topology_t topology, nvmlDevice_t device)
    -
    133{
    -
    134 hwloc_obj_t osdev;
    -
    135 nvmlReturn_t nvres;
    -
    136 nvmlPciInfo_t pci;
    -
    137 char uuid[64];
    -
    138
    -
    139 if (!hwloc_topology_is_thissystem(topology)) {
    -
    140 errno = EINVAL;
    -
    141 return NULL;
    -
    142 }
    -
    143
    -
    144 nvres = nvmlDeviceGetPciInfo(device, &pci);
    -
    145 if (NVML_SUCCESS != nvres)
    -
    146 return NULL;
    -
    147
    -
    148 nvres = nvmlDeviceGetUUID(device, uuid, sizeof(uuid));
    -
    149 if (NVML_SUCCESS != nvres)
    -
    150 uuid[0] = '\0';
    -
    151
    -
    152 osdev = NULL;
    -
    153 while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
    -
    154 hwloc_obj_t pcidev = osdev->parent;
    -
    155 const char *info;
    -
    156
    -
    157 if (strncmp(osdev->name, "nvml", 4))
    -
    158 continue;
    -
    159
    -
    160 if (pcidev
    -
    161 && pcidev->type == HWLOC_OBJ_PCI_DEVICE
    -
    162 && pcidev->attr->pcidev.domain == pci.domain
    -
    163 && pcidev->attr->pcidev.bus == pci.bus
    -
    164 && pcidev->attr->pcidev.dev == pci.device
    -
    165 && pcidev->attr->pcidev.func == 0)
    -
    166 return osdev;
    -
    167
    -
    168 info = hwloc_obj_get_info_by_name(osdev, "NVIDIAUUID");
    -
    169 if (info && !strcmp(info, uuid))
    -
    170 return osdev;
    -
    171 }
    -
    172
    -
    173 return NULL;
    -
    174}
    -
    175
    -
    179#ifdef __cplusplus
    -
    180} /* extern "C" */
    -
    181#endif
    -
    182
    -
    183
    -
    184#endif /* HWLOC_NVML_H */
    -
    hwloc_cpuset_t
    hwloc_bitmap_t hwloc_cpuset_t
    A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
    Definition: hwloc.h:161
    -
    HWLOC_OBJ_OSDEV_GPU
    @ HWLOC_OBJ_OSDEV_GPU
    Operating system GPU device. For instance ":0.0" for a GL display, "card0" for a Linux DRM device.
    Definition: hwloc.h:363
    -
    HWLOC_OBJ_PCI_DEVICE
    @ HWLOC_OBJ_PCI_DEVICE
    PCI device (filtered out by default).
    Definition: hwloc.h:290
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:716
    -
    hwloc_obj_get_info_by_name
    static const char * hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name)
    Search the given key name in object infos and return the corresponding value.
    -
    hwloc_topology_is_thissystem
    int hwloc_topology_is_thissystem(hwloc_topology_t restrict topology)
    Does the topology context come from this system?
    -
    hwloc_topology_get_complete_cpuset
    hwloc_const_cpuset_t hwloc_topology_get_complete_cpuset(hwloc_topology_t topology)
    Get complete CPU set.
    -
    hwloc_get_next_osdev
    static hwloc_obj_t hwloc_get_next_osdev(hwloc_topology_t topology, hwloc_obj_t prev)
    Get the next OS device in the system.
    Definition: helper.h:1280
    -
    hwloc_bitmap_iszero
    int hwloc_bitmap_iszero(hwloc_const_bitmap_t bitmap)
    Test whether bitmap bitmap is empty.
    -
    hwloc_bitmap_copy
    int hwloc_bitmap_copy(hwloc_bitmap_t dst, hwloc_const_bitmap_t src)
    Copy the contents of bitmap src into the already allocated bitmap dst.
    -
    hwloc_linux_read_path_as_cpumask
    int hwloc_linux_read_path_as_cpumask(const char *path, hwloc_bitmap_t set)
    Convert a linux kernel cpumask file path into a hwloc bitmap set.
    -
    hwloc_nvml_get_device_cpuset
    static int hwloc_nvml_get_device_cpuset(hwloc_topology_t topology, nvmlDevice_t device, hwloc_cpuset_t set)
    Get the CPU set of processors that are physically close to NVML device device.
    Definition: nvml.h:59
    -
    hwloc_nvml_get_device_osdev_by_index
    static hwloc_obj_t hwloc_nvml_get_device_osdev_by_index(hwloc_topology_t topology, unsigned idx)
    Get the hwloc OS device object corresponding to the NVML device whose index is idx.
    Definition: nvml.h:105
    -
    hwloc_nvml_get_device_osdev
    static hwloc_obj_t hwloc_nvml_get_device_osdev(hwloc_topology_t topology, nvmlDevice_t device)
    Get the hwloc OS device object corresponding to NVML device device.
    Definition: nvml.h:132
    -
    hwloc_obj
    Structure of a topology object.
    Definition: hwloc.h:420
    -
    hwloc_obj::name
    char * name
    Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name str...
    Definition: hwloc.h:432
    -
    hwloc_obj::type
    hwloc_obj_type_t type
    Type of object.
    Definition: hwloc.h:422
    -
    hwloc_obj::attr
    union hwloc_obj_attr_u * attr
    Object type-specific Attributes, may be NULL if no attribute value was found.
    Definition: hwloc.h:439
    -
    hwloc_obj::parent
    struct hwloc_obj * parent
    Parent, NULL if root (Machine object)
    Definition: hwloc.h:470
    -
    hwloc_obj_attr_u::pcidev
    struct hwloc_obj_attr_u::hwloc_pcidev_attr_s pcidev
    -
    hwloc_obj_attr_u::osdev
    struct hwloc_obj_attr_u::hwloc_osdev_attr_s osdev
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::dev
    unsigned char dev
    Definition: hwloc.h:663
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::func
    unsigned char func
    Definition: hwloc.h:663
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::domain
    unsigned short domain
    Definition: hwloc.h:659
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::bus
    unsigned char bus
    Definition: hwloc.h:663
    -
    hwloc_obj_attr_u::hwloc_osdev_attr_s::type
    hwloc_obj_osdev_type_t type
    Definition: hwloc.h:690
    -
    - - - - - - - - -
    -
    rsmi.h
    -
    -
    -
    1/*
    -
    2 * Copyright © 2012-2023 Inria. All rights reserved.
    -
    3 * Copyright (c) 2020, Advanced Micro Devices, Inc. All rights reserved.
    -
    4 * Written by Advanced Micro Devices,
    -
    5 * See COPYING in top-level directory.
    -
    6 */
    -
    7
    -
    15#ifndef HWLOC_RSMI_H
    -
    16#define HWLOC_RSMI_H
    -
    17
    -
    18#include "hwloc.h"
    -
    19#include "hwloc/autogen/config.h"
    -
    20#include "hwloc/helper.h"
    -
    21#ifdef HWLOC_LINUX_SYS
    -
    22#include "hwloc/linux.h"
    -
    23#endif
    -
    24
    -
    25#include <rocm_smi/rocm_smi.h>
    -
    26
    -
    27
    -
    28#ifdef __cplusplus
    -
    29extern "C" {
    -
    30#endif
    -
    31
    -
    32
    -
    62static __hwloc_inline int
    -
    63hwloc_rsmi_get_device_cpuset(hwloc_topology_t topology __hwloc_attribute_unused,
    -
    64 uint32_t dv_ind, hwloc_cpuset_t set)
    -
    65{
    -
    66#ifdef HWLOC_LINUX_SYS
    -
    67 /* If we're on Linux, use the sysfs mechanism to get the local cpus */
    -
    68#define HWLOC_RSMI_DEVICE_SYSFS_PATH_MAX 128
    -
    69 char path[HWLOC_RSMI_DEVICE_SYSFS_PATH_MAX];
    -
    70 rsmi_status_t ret;
    -
    71 uint64_t bdfid = 0;
    -
    72 unsigned domain, device, bus;
    -
    73
    -
    74 if (!hwloc_topology_is_thissystem(topology)) {
    -
    75 errno = EINVAL;
    -
    76 return -1;
    -
    77 }
    -
    78
    -
    79 ret = rsmi_dev_pci_id_get(dv_ind, &bdfid);
    -
    80 if (RSMI_STATUS_SUCCESS != ret) {
    -
    81 errno = EINVAL;
    -
    82 return -1;
    -
    83 }
    -
    84 domain = (bdfid>>32) & 0xffffffff;
    -
    85 bus = ((bdfid & 0xffff)>>8) & 0xff;
    -
    86 device = ((bdfid & 0xff)>>3) & 0x1f;
    -
    87
    -
    88 sprintf(path, "/sys/bus/pci/devices/%04x:%02x:%02x.0/local_cpus", domain, bus, device);
    -
    89 if (hwloc_linux_read_path_as_cpumask(path, set) < 0
    -
    90 || hwloc_bitmap_iszero(set))
    -
    91 hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
    -
    92#else
    -
    93 /* Non-Linux systems simply get a full cpuset */
    -
    94 hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
    -
    95#endif
    -
    96 return 0;
    -
    97}
    -
    98
    -
    114static __hwloc_inline hwloc_obj_t
    -
    115hwloc_rsmi_get_device_osdev_by_index(hwloc_topology_t topology, uint32_t dv_ind)
    -
    116{
    -
    117 hwloc_obj_t osdev = NULL;
    -
    118 while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
    -
    119 if (HWLOC_OBJ_OSDEV_GPU == osdev->attr->osdev.type
    -
    120 && osdev->name
    -
    121 && !strncmp("rsmi", osdev->name, 4)
    -
    122 && atoi(osdev->name + 4) == (int) dv_ind)
    -
    123 return osdev;
    -
    124 }
    -
    125 return NULL;
    -
    126}
    -
    127
    -
    143static __hwloc_inline hwloc_obj_t
    -
    144hwloc_rsmi_get_device_osdev(hwloc_topology_t topology, uint32_t dv_ind)
    -
    145{
    -
    146 hwloc_obj_t osdev;
    -
    147 rsmi_status_t ret;
    -
    148 uint64_t bdfid = 0;
    -
    149 unsigned domain, device, bus, func;
    -
    150 uint64_t id;
    -
    151 char uuid[64];
    -
    152
    -
    153 if (!hwloc_topology_is_thissystem(topology)) {
    -
    154 errno = EINVAL;
    -
    155 return NULL;
    -
    156 }
    -
    157
    -
    158 ret = rsmi_dev_pci_id_get(dv_ind, &bdfid);
    -
    159 if (RSMI_STATUS_SUCCESS != ret) {
    -
    160 errno = EINVAL;
    -
    161 return NULL;
    -
    162 }
    -
    163 domain = (bdfid>>32) & 0xffffffff;
    -
    164 bus = ((bdfid & 0xffff)>>8) & 0xff;
    -
    165 device = ((bdfid & 0xff)>>3) & 0x1f;
    -
    166 func = bdfid & 0x7;
    -
    167
    -
    168 ret = rsmi_dev_unique_id_get(dv_ind, &id);
    -
    169 if (RSMI_STATUS_SUCCESS != ret)
    -
    170 uuid[0] = '\0';
    -
    171 else
    -
    172 sprintf(uuid, "%lx", id);
    -
    173
    -
    174 osdev = NULL;
    -
    175 while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
    -
    176 hwloc_obj_t pcidev = osdev->parent;
    -
    177 const char *info;
    -
    178
    -
    179 if (strncmp(osdev->name, "rsmi", 4))
    -
    180 continue;
    -
    181
    -
    182 if (pcidev
    -
    183 && pcidev->type == HWLOC_OBJ_PCI_DEVICE
    -
    184 && pcidev->attr->pcidev.domain == domain
    -
    185 && pcidev->attr->pcidev.bus == bus
    -
    186 && pcidev->attr->pcidev.dev == device
    -
    187 && pcidev->attr->pcidev.func == func)
    -
    188 return osdev;
    -
    189
    -
    190 info = hwloc_obj_get_info_by_name(osdev, "AMDUUID");
    -
    191 if (info && !strcmp(info, uuid))
    -
    192 return osdev;
    -
    193 }
    -
    194
    -
    195 return NULL;
    -
    196}
    -
    197
    -
    201#ifdef __cplusplus
    -
    202} /* extern "C" */
    -
    203#endif
    -
    204
    -
    205
    -
    206#endif /* HWLOC_RSMI_H */
    -
    hwloc_cpuset_t
    hwloc_bitmap_t hwloc_cpuset_t
    A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
    Definition: hwloc.h:161
    -
    HWLOC_OBJ_OSDEV_GPU
    @ HWLOC_OBJ_OSDEV_GPU
    Operating system GPU device. For instance ":0.0" for a GL display, "card0" for a Linux DRM device.
    Definition: hwloc.h:363
    -
    HWLOC_OBJ_PCI_DEVICE
    @ HWLOC_OBJ_PCI_DEVICE
    PCI device (filtered out by default).
    Definition: hwloc.h:290
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:716
    -
    hwloc_obj_get_info_by_name
    static const char * hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name)
    Search the given key name in object infos and return the corresponding value.
    -
    hwloc_topology_is_thissystem
    int hwloc_topology_is_thissystem(hwloc_topology_t restrict topology)
    Does the topology context come from this system?
    -
    hwloc_topology_get_complete_cpuset
    hwloc_const_cpuset_t hwloc_topology_get_complete_cpuset(hwloc_topology_t topology)
    Get complete CPU set.
    -
    hwloc_get_next_osdev
    static hwloc_obj_t hwloc_get_next_osdev(hwloc_topology_t topology, hwloc_obj_t prev)
    Get the next OS device in the system.
    Definition: helper.h:1280
    -
    hwloc_bitmap_iszero
    int hwloc_bitmap_iszero(hwloc_const_bitmap_t bitmap)
    Test whether bitmap bitmap is empty.
    -
    hwloc_bitmap_copy
    int hwloc_bitmap_copy(hwloc_bitmap_t dst, hwloc_const_bitmap_t src)
    Copy the contents of bitmap src into the already allocated bitmap dst.
    -
    hwloc_linux_read_path_as_cpumask
    int hwloc_linux_read_path_as_cpumask(const char *path, hwloc_bitmap_t set)
    Convert a linux kernel cpumask file path into a hwloc bitmap set.
    -
    hwloc_rsmi_get_device_osdev_by_index
    static hwloc_obj_t hwloc_rsmi_get_device_osdev_by_index(hwloc_topology_t topology, uint32_t dv_ind)
    Get the hwloc OS device object corresponding to the AMD GPU device whose index is dv_ind.
    Definition: rsmi.h:115
    -
    hwloc_rsmi_get_device_osdev
    static hwloc_obj_t hwloc_rsmi_get_device_osdev(hwloc_topology_t topology, uint32_t dv_ind)
    Get the hwloc OS device object corresponding to AMD GPU device, whose index is dv_ind.
    Definition: rsmi.h:144
    -
    hwloc_rsmi_get_device_cpuset
    static int hwloc_rsmi_get_device_cpuset(hwloc_topology_t topology, uint32_t dv_ind, hwloc_cpuset_t set)
    Get the CPU set of logical processors that are physically close to AMD GPU device whose index is dv_i...
    Definition: rsmi.h:63
    -
    hwloc_obj
    Structure of a topology object.
    Definition: hwloc.h:420
    -
    hwloc_obj::name
    char * name
    Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name str...
    Definition: hwloc.h:432
    -
    hwloc_obj::type
    hwloc_obj_type_t type
    Type of object.
    Definition: hwloc.h:422
    -
    hwloc_obj::attr
    union hwloc_obj_attr_u * attr
    Object type-specific Attributes, may be NULL if no attribute value was found.
    Definition: hwloc.h:439
    -
    hwloc_obj::parent
    struct hwloc_obj * parent
    Parent, NULL if root (Machine object)
    Definition: hwloc.h:470
    -
    hwloc_obj_attr_u::pcidev
    struct hwloc_obj_attr_u::hwloc_pcidev_attr_s pcidev
    -
    hwloc_obj_attr_u::osdev
    struct hwloc_obj_attr_u::hwloc_osdev_attr_s osdev
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::dev
    unsigned char dev
    Definition: hwloc.h:663
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::func
    unsigned char func
    Definition: hwloc.h:663
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::domain
    unsigned short domain
    Definition: hwloc.h:659
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::bus
    unsigned char bus
    Definition: hwloc.h:663
    -
    hwloc_obj_attr_u::hwloc_osdev_attr_s::type
    hwloc_obj_osdev_type_t type
    Definition: hwloc.h:690
    -
    - - - - - - - - -
    -
    levelzero.h
    -
    -
    -
    1/*
    -
    2 * Copyright © 2021-2023 Inria. All rights reserved.
    -
    3 * See COPYING in top-level directory.
    -
    4 */
    -
    5
    -
    13#ifndef HWLOC_LEVELZERO_H
    -
    14#define HWLOC_LEVELZERO_H
    -
    15
    -
    16#include "hwloc.h"
    -
    17#include "hwloc/autogen/config.h"
    -
    18#include "hwloc/helper.h"
    -
    19#ifdef HWLOC_LINUX_SYS
    -
    20#include "hwloc/linux.h"
    -
    21#endif
    -
    22
    -
    23#include <level_zero/ze_api.h>
    -
    24#include <level_zero/zes_api.h>
    -
    25
    -
    26
    -
    27#ifdef __cplusplus
    -
    28extern "C" {
    -
    29#endif
    -
    30
    -
    31
    -
    62static __hwloc_inline int
    -
    63hwloc_levelzero_get_device_cpuset(hwloc_topology_t topology __hwloc_attribute_unused,
    -
    64 ze_device_handle_t device, hwloc_cpuset_t set)
    -
    65{
    -
    66#ifdef HWLOC_LINUX_SYS
    -
    67 /* If we're on Linux, use the sysfs mechanism to get the local cpus */
    -
    68#define HWLOC_LEVELZERO_DEVICE_SYSFS_PATH_MAX 128
    -
    69 char path[HWLOC_LEVELZERO_DEVICE_SYSFS_PATH_MAX];
    -
    70 zes_pci_properties_t pci;
    -
    71 zes_device_handle_t sdevice = device;
    -
    72 ze_result_t res;
    -
    73
    -
    74 if (!hwloc_topology_is_thissystem(topology)) {
    -
    75 errno = EINVAL;
    -
    76 return -1;
    -
    77 }
    -
    78
    -
    79 res = zesDevicePciGetProperties(sdevice, &pci);
    -
    80 if (res != ZE_RESULT_SUCCESS) {
    -
    81 errno = EINVAL;
    -
    82 return -1;
    -
    83 }
    -
    84
    -
    85 sprintf(path, "/sys/bus/pci/devices/%04x:%02x:%02x.%01x/local_cpus",
    -
    86 pci.address.domain, pci.address.bus, pci.address.device, pci.address.function);
    -
    87 if (hwloc_linux_read_path_as_cpumask(path, set) < 0
    -
    88 || hwloc_bitmap_iszero(set))
    -
    89 hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
    -
    90#else
    -
    91 /* Non-Linux systems simply get a full cpuset */
    -
    92 hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
    -
    93#endif
    -
    94 return 0;
    -
    95}
    -
    96
    -
    111static __hwloc_inline hwloc_obj_t
    -
    112hwloc_levelzero_get_device_osdev(hwloc_topology_t topology, ze_device_handle_t device)
    -
    113{
    -
    114 zes_device_handle_t sdevice = device;
    -
    115 zes_pci_properties_t pci;
    -
    116 ze_result_t res;
    -
    117 hwloc_obj_t osdev;
    -
    118
    -
    119 if (!hwloc_topology_is_thissystem(topology)) {
    -
    120 errno = EINVAL;
    -
    121 return NULL;
    -
    122 }
    -
    123
    -
    124 res = zesDevicePciGetProperties(sdevice, &pci);
    -
    125 if (res != ZE_RESULT_SUCCESS) {
    -
    126 /* L0 was likely initialized without sysman, don't bother */
    -
    127 errno = EINVAL;
    -
    128 return NULL;
    -
    129 }
    -
    130
    -
    131 osdev = NULL;
    -
    132 while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
    -
    133 hwloc_obj_t pcidev = osdev->parent;
    -
    134
    -
    135 if (strncmp(osdev->name, "ze", 2))
    -
    136 continue;
    -
    137
    -
    138 if (pcidev
    -
    139 && pcidev->type == HWLOC_OBJ_PCI_DEVICE
    -
    140 && pcidev->attr->pcidev.domain == pci.address.domain
    -
    141 && pcidev->attr->pcidev.bus == pci.address.bus
    -
    142 && pcidev->attr->pcidev.dev == pci.address.device
    -
    143 && pcidev->attr->pcidev.func == pci.address.function)
    -
    144 return osdev;
    -
    145
    -
    146 /* FIXME: when we'll have serialnumber, try it in case PCI is filtered-out */
    -
    147 }
    -
    148
    -
    149 return NULL;
    -
    150}
    -
    151
    -
    155#ifdef __cplusplus
    -
    156} /* extern "C" */
    -
    157#endif
    -
    158
    -
    159
    -
    160#endif /* HWLOC_LEVELZERO_H */
    -
    hwloc_cpuset_t
    hwloc_bitmap_t hwloc_cpuset_t
    A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
    Definition: hwloc.h:161
    -
    HWLOC_OBJ_PCI_DEVICE
    @ HWLOC_OBJ_PCI_DEVICE
    PCI device (filtered out by default).
    Definition: hwloc.h:290
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:716
    -
    hwloc_topology_is_thissystem
    int hwloc_topology_is_thissystem(hwloc_topology_t restrict topology)
    Does the topology context come from this system?
    -
    hwloc_topology_get_complete_cpuset
    hwloc_const_cpuset_t hwloc_topology_get_complete_cpuset(hwloc_topology_t topology)
    Get complete CPU set.
    -
    hwloc_get_next_osdev
    static hwloc_obj_t hwloc_get_next_osdev(hwloc_topology_t topology, hwloc_obj_t prev)
    Get the next OS device in the system.
    Definition: helper.h:1280
    -
    hwloc_bitmap_iszero
    int hwloc_bitmap_iszero(hwloc_const_bitmap_t bitmap)
    Test whether bitmap bitmap is empty.
    -
    hwloc_bitmap_copy
    int hwloc_bitmap_copy(hwloc_bitmap_t dst, hwloc_const_bitmap_t src)
    Copy the contents of bitmap src into the already allocated bitmap dst.
    -
    hwloc_linux_read_path_as_cpumask
    int hwloc_linux_read_path_as_cpumask(const char *path, hwloc_bitmap_t set)
    Convert a linux kernel cpumask file path into a hwloc bitmap set.
    -
    hwloc_levelzero_get_device_cpuset
    static int hwloc_levelzero_get_device_cpuset(hwloc_topology_t topology, ze_device_handle_t device, hwloc_cpuset_t set)
    Get the CPU set of logical processors that are physically close to the Level Zero device device.
    Definition: levelzero.h:63
    -
    hwloc_levelzero_get_device_osdev
    static hwloc_obj_t hwloc_levelzero_get_device_osdev(hwloc_topology_t topology, ze_device_handle_t device)
    Get the hwloc OS device object corresponding to Level Zero device device.
    Definition: levelzero.h:112
    -
    hwloc_obj
    Structure of a topology object.
    Definition: hwloc.h:420
    -
    hwloc_obj::name
    char * name
    Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name str...
    Definition: hwloc.h:432
    -
    hwloc_obj::type
    hwloc_obj_type_t type
    Type of object.
    Definition: hwloc.h:422
    -
    hwloc_obj::attr
    union hwloc_obj_attr_u * attr
    Object type-specific Attributes, may be NULL if no attribute value was found.
    Definition: hwloc.h:439
    -
    hwloc_obj::parent
    struct hwloc_obj * parent
    Parent, NULL if root (Machine object)
    Definition: hwloc.h:470
    -
    hwloc_obj_attr_u::pcidev
    struct hwloc_obj_attr_u::hwloc_pcidev_attr_s pcidev
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::dev
    unsigned char dev
    Definition: hwloc.h:663
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::func
    unsigned char func
    Definition: hwloc.h:663
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::domain
    unsigned short domain
    Definition: hwloc.h:659
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::bus
    unsigned char bus
    Definition: hwloc.h:663
    -
    - - - - - - - - -
    -
    gl.h
    -
    -
    -
    1/*
    -
    2 * Copyright © 2012 Blue Brain Project, EPFL. All rights reserved.
    -
    3 * Copyright © 2012-2023 Inria. All rights reserved.
    -
    4 * See COPYING in top-level directory.
    -
    5 */
    -
    6
    -
    14#ifndef HWLOC_GL_H
    -
    15#define HWLOC_GL_H
    -
    16
    -
    17#include "hwloc.h"
    -
    18
    -
    19#include <stdio.h>
    -
    20#include <string.h>
    -
    21
    -
    22
    -
    23#ifdef __cplusplus
    -
    24extern "C" {
    -
    25#endif
    -
    26
    -
    27
    -
    53static __hwloc_inline hwloc_obj_t
    -
    54hwloc_gl_get_display_osdev_by_port_device(hwloc_topology_t topology,
    -
    55 unsigned port, unsigned device)
    -
    56{
    -
    57 unsigned x = (unsigned) -1, y = (unsigned) -1;
    -
    58 hwloc_obj_t osdev = NULL;
    -
    59 while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
    -
    60 if (HWLOC_OBJ_OSDEV_GPU == osdev->attr->osdev.type
    -
    61 && osdev->name
    -
    62 && sscanf(osdev->name, ":%u.%u", &x, &y) == 2
    -
    63 && port == x && device == y)
    -
    64 return osdev;
    -
    65 }
    -
    66 errno = EINVAL;
    -
    67 return NULL;
    -
    68}
    -
    69
    -
    84static __hwloc_inline hwloc_obj_t
    -
    85hwloc_gl_get_display_osdev_by_name(hwloc_topology_t topology,
    -
    86 const char *name)
    -
    87{
    -
    88 hwloc_obj_t osdev = NULL;
    -
    89 while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
    -
    90 if (HWLOC_OBJ_OSDEV_GPU == osdev->attr->osdev.type
    -
    91 && osdev->name
    -
    92 && !strcmp(name, osdev->name))
    -
    93 return osdev;
    -
    94 }
    -
    95 errno = EINVAL;
    -
    96 return NULL;
    -
    97}
    -
    98
    -
    112static __hwloc_inline int
    -
    113hwloc_gl_get_display_by_osdev(hwloc_topology_t topology __hwloc_attribute_unused,
    -
    114 hwloc_obj_t osdev,
    -
    115 unsigned *port, unsigned *device)
    -
    116{
    -
    117 unsigned x = -1, y = -1;
    -
    118 if (HWLOC_OBJ_OSDEV_GPU == osdev->attr->osdev.type
    -
    119 && sscanf(osdev->name, ":%u.%u", &x, &y) == 2) {
    -
    120 *port = x;
    -
    121 *device = y;
    -
    122 return 0;
    -
    123 }
    -
    124 errno = EINVAL;
    -
    125 return -1;
    -
    126}
    -
    127
    -
    131#ifdef __cplusplus
    -
    132} /* extern "C" */
    -
    133#endif
    -
    134
    -
    135
    -
    136#endif /* HWLOC_GL_H */
    -
    137
    -
    HWLOC_OBJ_OSDEV_GPU
    @ HWLOC_OBJ_OSDEV_GPU
    Operating system GPU device. For instance ":0.0" for a GL display, "card0" for a Linux DRM device.
    Definition: hwloc.h:363
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:716
    -
    hwloc_get_next_osdev
    static hwloc_obj_t hwloc_get_next_osdev(hwloc_topology_t topology, hwloc_obj_t prev)
    Get the next OS device in the system.
    Definition: helper.h:1280
    -
    hwloc_gl_get_display_osdev_by_name
    static hwloc_obj_t hwloc_gl_get_display_osdev_by_name(hwloc_topology_t topology, const char *name)
    Get the hwloc OS device object corresponding to the OpenGL display given by name.
    Definition: gl.h:85
    -
    hwloc_gl_get_display_osdev_by_port_device
    static hwloc_obj_t hwloc_gl_get_display_osdev_by_port_device(hwloc_topology_t topology, unsigned port, unsigned device)
    Get the hwloc OS device object corresponding to the OpenGL display given by port and device index.
    Definition: gl.h:54
    -
    hwloc_gl_get_display_by_osdev
    static int hwloc_gl_get_display_by_osdev(hwloc_topology_t topology, hwloc_obj_t osdev, unsigned *port, unsigned *device)
    Get the OpenGL display port and device corresponding to the given hwloc OS object.
    Definition: gl.h:113
    -
    hwloc_obj
    Structure of a topology object.
    Definition: hwloc.h:420
    -
    hwloc_obj::name
    char * name
    Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name str...
    Definition: hwloc.h:432
    -
    hwloc_obj::attr
    union hwloc_obj_attr_u * attr
    Object type-specific Attributes, may be NULL if no attribute value was found.
    Definition: hwloc.h:439
    -
    hwloc_obj_attr_u::osdev
    struct hwloc_obj_attr_u::hwloc_osdev_attr_s osdev
    -
    hwloc_obj_attr_u::hwloc_osdev_attr_s::type
    hwloc_obj_osdev_type_t type
    Definition: hwloc.h:690
    -
    - - - - - - - - -
    -
    openfabrics-verbs.h
    -
    -
    -
    1/*
    -
    2 * Copyright © 2009 CNRS
    -
    3 * Copyright © 2009-2023 Inria. All rights reserved.
    -
    4 * Copyright © 2009-2010 Université Bordeaux
    -
    5 * Copyright © 2009-2011 Cisco Systems, Inc. All rights reserved.
    -
    6 * See COPYING in top-level directory.
    -
    7 */
    -
    8
    -
    19#ifndef HWLOC_OPENFABRICS_VERBS_H
    -
    20#define HWLOC_OPENFABRICS_VERBS_H
    -
    21
    -
    22#include "hwloc.h"
    -
    23#include "hwloc/autogen/config.h"
    -
    24#ifdef HWLOC_LINUX_SYS
    -
    25#include "hwloc/linux.h"
    -
    26#endif
    -
    27
    -
    28#include <infiniband/verbs.h>
    -
    29
    -
    30
    -
    31#ifdef __cplusplus
    -
    32extern "C" {
    -
    33#endif
    -
    34
    -
    35
    -
    64static __hwloc_inline int
    -
    65hwloc_ibv_get_device_cpuset(hwloc_topology_t topology __hwloc_attribute_unused,
    -
    66 struct ibv_device *ibdev, hwloc_cpuset_t set)
    -
    67{
    -
    68#ifdef HWLOC_LINUX_SYS
    -
    69 /* If we're on Linux, use the verbs-provided sysfs mechanism to
    -
    70 get the local cpus */
    -
    71#define HWLOC_OPENFABRICS_VERBS_SYSFS_PATH_MAX 128
    -
    72 char path[HWLOC_OPENFABRICS_VERBS_SYSFS_PATH_MAX];
    -
    73
    -
    74 if (!hwloc_topology_is_thissystem(topology)) {
    -
    75 errno = EINVAL;
    -
    76 return -1;
    -
    77 }
    -
    78
    -
    79 sprintf(path, "/sys/class/infiniband/%s/device/local_cpus",
    -
    80 ibv_get_device_name(ibdev));
    -
    81 if (hwloc_linux_read_path_as_cpumask(path, set) < 0
    -
    82 || hwloc_bitmap_iszero(set))
    -
    83 hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
    -
    84#else
    -
    85 /* Non-Linux systems simply get a full cpuset */
    -
    86 hwloc_bitmap_copy(set, hwloc_topology_get_complete_cpuset(topology));
    -
    87#endif
    -
    88 return 0;
    -
    89}
    -
    90
    -
    108static __hwloc_inline hwloc_obj_t
    -
    109hwloc_ibv_get_device_osdev_by_name(hwloc_topology_t topology,
    -
    110 const char *ibname)
    -
    111{
    -
    112 hwloc_obj_t osdev = NULL;
    -
    113 while ((osdev = hwloc_get_next_osdev(topology, osdev)) != NULL) {
    -
    114 if (HWLOC_OBJ_OSDEV_OPENFABRICS == osdev->attr->osdev.type
    -
    115 && osdev->name && !strcmp(ibname, osdev->name))
    -
    116 return osdev;
    -
    117 }
    -
    118 return NULL;
    -
    119}
    -
    120
    -
    136static __hwloc_inline hwloc_obj_t
    -
    137hwloc_ibv_get_device_osdev(hwloc_topology_t topology,
    -
    138 struct ibv_device *ibdev)
    -
    139{
    -
    140 if (!hwloc_topology_is_thissystem(topology)) {
    -
    141 errno = EINVAL;
    -
    142 return NULL;
    -
    143 }
    -
    144 return hwloc_ibv_get_device_osdev_by_name(topology, ibv_get_device_name(ibdev));
    -
    145}
    -
    146
    -
    150#ifdef __cplusplus
    -
    151} /* extern "C" */
    -
    152#endif
    -
    153
    -
    154
    -
    155#endif /* HWLOC_OPENFABRICS_VERBS_H */
    -
    hwloc_cpuset_t
    hwloc_bitmap_t hwloc_cpuset_t
    A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
    Definition: hwloc.h:161
    -
    HWLOC_OBJ_OSDEV_OPENFABRICS
    @ HWLOC_OBJ_OSDEV_OPENFABRICS
    Operating system openfabrics device. For instance the "mlx4_0" InfiniBand HCA, "hfi1_0" Omni-Path int...
    Definition: hwloc.h:368
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:716
    -
    hwloc_topology_is_thissystem
    int hwloc_topology_is_thissystem(hwloc_topology_t restrict topology)
    Does the topology context come from this system?
    -
    hwloc_topology_get_complete_cpuset
    hwloc_const_cpuset_t hwloc_topology_get_complete_cpuset(hwloc_topology_t topology)
    Get complete CPU set.
    -
    hwloc_get_next_osdev
    static hwloc_obj_t hwloc_get_next_osdev(hwloc_topology_t topology, hwloc_obj_t prev)
    Get the next OS device in the system.
    Definition: helper.h:1280
    -
    hwloc_bitmap_iszero
    int hwloc_bitmap_iszero(hwloc_const_bitmap_t bitmap)
    Test whether bitmap bitmap is empty.
    -
    hwloc_bitmap_copy
    int hwloc_bitmap_copy(hwloc_bitmap_t dst, hwloc_const_bitmap_t src)
    Copy the contents of bitmap src into the already allocated bitmap dst.
    -
    hwloc_linux_read_path_as_cpumask
    int hwloc_linux_read_path_as_cpumask(const char *path, hwloc_bitmap_t set)
    Convert a linux kernel cpumask file path into a hwloc bitmap set.
    -
    hwloc_ibv_get_device_osdev_by_name
    static hwloc_obj_t hwloc_ibv_get_device_osdev_by_name(hwloc_topology_t topology, const char *ibname)
    Get the hwloc OS device object corresponding to the OpenFabrics device named ibname.
    Definition: openfabrics-verbs.h:109
    -
    hwloc_ibv_get_device_cpuset
    static int hwloc_ibv_get_device_cpuset(hwloc_topology_t topology, struct ibv_device *ibdev, hwloc_cpuset_t set)
    Get the CPU set of processors that are physically close to device ibdev.
    Definition: openfabrics-verbs.h:65
    -
    hwloc_ibv_get_device_osdev
    static hwloc_obj_t hwloc_ibv_get_device_osdev(hwloc_topology_t topology, struct ibv_device *ibdev)
    Get the hwloc OS device object corresponding to the OpenFabrics device ibdev.
    Definition: openfabrics-verbs.h:137
    -
    hwloc_obj
    Structure of a topology object.
    Definition: hwloc.h:420
    -
    hwloc_obj::name
    char * name
    Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name str...
    Definition: hwloc.h:432
    -
    hwloc_obj::attr
    union hwloc_obj_attr_u * attr
    Object type-specific Attributes, may be NULL if no attribute value was found.
    Definition: hwloc.h:439
    -
    hwloc_obj_attr_u::osdev
    struct hwloc_obj_attr_u::hwloc_osdev_attr_s osdev
    -
    hwloc_obj_attr_u::hwloc_osdev_attr_s::type
    hwloc_obj_osdev_type_t type
    Definition: hwloc.h:690
    -
    - - - - - - - - -
    -
    diff.h
    -
    -
    -
    1/*
    -
    2 * Copyright © 2013-2023 Inria. All rights reserved.
    -
    3 * See COPYING in top-level directory.
    -
    4 */
    -
    5
    -
    10#ifndef HWLOC_DIFF_H
    -
    11#define HWLOC_DIFF_H
    -
    12
    -
    13#ifndef HWLOC_H
    -
    14#error Please include the main hwloc.h instead
    -
    15#endif
    -
    16
    -
    17
    -
    18#ifdef __cplusplus
    -
    19extern "C" {
    -
    20#elif 0
    -
    21}
    -
    22#endif
    -
    23
    -
    24
    -
    62typedef enum hwloc_topology_diff_obj_attr_type_e {
    -
    67 HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_SIZE,
    -
    68
    -
    74 HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_NAME,
    -
    78 HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_INFO
    -
    79} hwloc_topology_diff_obj_attr_type_t;
    -
    80
    -
    83union hwloc_topology_diff_obj_attr_u {
    -
    84 struct hwloc_topology_diff_obj_attr_generic_s {
    -
    85 /* each part of the union must start with these */
    -
    86 hwloc_topology_diff_obj_attr_type_t type;
    -
    87 } generic;
    -
    88
    -
    90 struct hwloc_topology_diff_obj_attr_uint64_s {
    -
    91 /* used for storing integer attributes */
    -
    92 hwloc_topology_diff_obj_attr_type_t type;
    -
    93 hwloc_uint64_t index; /* not used for SIZE */
    -
    94 hwloc_uint64_t oldvalue;
    -
    95 hwloc_uint64_t newvalue;
    -
    96 } uint64;
    -
    97
    -
    99 struct hwloc_topology_diff_obj_attr_string_s {
    -
    100 /* used for storing name and info pairs */
    -
    101 hwloc_topology_diff_obj_attr_type_t type;
    -
    102 char *name; /* not used for NAME */
    -
    103 char *oldvalue;
    -
    104 char *newvalue;
    -
    105 } string;
    -
    106};
    -
    107
    -
    108
    -
    111typedef enum hwloc_topology_diff_type_e {
    -
    115 HWLOC_TOPOLOGY_DIFF_OBJ_ATTR,
    -
    116
    -
    124 HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX
    -
    125} hwloc_topology_diff_type_t;
    -
    126
    -
    129typedef union hwloc_topology_diff_u {
    -
    130 struct hwloc_topology_diff_generic_s {
    -
    131 /* each part of the union must start with these */
    -
    132 hwloc_topology_diff_type_t type;
    -
    133 union hwloc_topology_diff_u * next; /* pointer to the next element of the list, or NULL */
    -
    134 } generic;
    -
    135
    -
    136 /* A difference in an object attribute. */
    -
    137 struct hwloc_topology_diff_obj_attr_s {
    -
    138 hwloc_topology_diff_type_t type; /* must be ::HWLOC_TOPOLOGY_DIFF_OBJ_ATTR */
    -
    139 union hwloc_topology_diff_u * next;
    -
    140 /* List of attribute differences for a single object */
    -
    141 int obj_depth;
    -
    142 unsigned obj_index;
    -
    143 union hwloc_topology_diff_obj_attr_u diff;
    -
    144 } obj_attr;
    -
    145
    -
    146 /* A difference that is too complex. */
    -
    147 struct hwloc_topology_diff_too_complex_s {
    -
    148 hwloc_topology_diff_type_t type; /* must be ::HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX */
    -
    149 union hwloc_topology_diff_u * next;
    -
    150 /* Where we had to stop computing the diff in the first topology */
    -
    151 int obj_depth;
    -
    152 unsigned obj_index;
    -
    153 } too_complex;
    -
    154} * hwloc_topology_diff_t;
    -
    155
    -
    156
    -
    194HWLOC_DECLSPEC int hwloc_topology_diff_build(hwloc_topology_t topology, hwloc_topology_t newtopology, unsigned long flags, hwloc_topology_diff_t *diff);
    -
    195
    -
    198enum hwloc_topology_diff_apply_flags_e {
    -
    202 HWLOC_TOPOLOGY_DIFF_APPLY_REVERSE = (1UL<<0)
    -
    203};
    -
    204
    -
    222HWLOC_DECLSPEC int hwloc_topology_diff_apply(hwloc_topology_t topology, hwloc_topology_diff_t diff, unsigned long flags);
    -
    223
    -
    228HWLOC_DECLSPEC int hwloc_topology_diff_destroy(hwloc_topology_diff_t diff);
    -
    229
    -
    243HWLOC_DECLSPEC int hwloc_topology_diff_load_xml(const char *xmlpath, hwloc_topology_diff_t *diff, char **refname);
    -
    244
    -
    256HWLOC_DECLSPEC int hwloc_topology_diff_export_xml(hwloc_topology_diff_t diff, const char *refname, const char *xmlpath);
    -
    257
    -
    271HWLOC_DECLSPEC int hwloc_topology_diff_load_xmlbuffer(const char *xmlbuffer, int buflen, hwloc_topology_diff_t *diff, char **refname);
    -
    272
    -
    289HWLOC_DECLSPEC int hwloc_topology_diff_export_xmlbuffer(hwloc_topology_diff_t diff, const char *refname, char **xmlbuffer, int *buflen);
    -
    290
    -
    294#ifdef __cplusplus
    -
    295} /* extern "C" */
    -
    296#endif
    -
    297
    -
    298
    -
    299#endif /* HWLOC_DIFF_H */
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:716
    -
    hwloc_topology_diff_t
    union hwloc_topology_diff_u * hwloc_topology_diff_t
    One element of a difference list between two topologies.
    -
    hwloc_topology_diff_load_xml
    int hwloc_topology_diff_load_xml(const char *xmlpath, hwloc_topology_diff_t *diff, char **refname)
    Load a list of topology differences from a XML file.
    -
    hwloc_topology_diff_type_e
    hwloc_topology_diff_type_e
    Type of one element of a difference list.
    Definition: diff.h:111
    -
    hwloc_topology_diff_destroy
    int hwloc_topology_diff_destroy(hwloc_topology_diff_t diff)
    Destroy a list of topology differences.
    -
    hwloc_topology_diff_obj_attr_type_t
    enum hwloc_topology_diff_obj_attr_type_e hwloc_topology_diff_obj_attr_type_t
    Type of one object attribute difference.
    -
    hwloc_topology_diff_type_t
    enum hwloc_topology_diff_type_e hwloc_topology_diff_type_t
    Type of one element of a difference list.
    -
    hwloc_topology_diff_obj_attr_type_e
    hwloc_topology_diff_obj_attr_type_e
    Type of one object attribute difference.
    Definition: diff.h:62
    -
    hwloc_topology_diff_export_xml
    int hwloc_topology_diff_export_xml(hwloc_topology_diff_t diff, const char *refname, const char *xmlpath)
    Export a list of topology differences to a XML file.
    -
    hwloc_topology_diff_build
    int hwloc_topology_diff_build(hwloc_topology_t topology, hwloc_topology_t newtopology, unsigned long flags, hwloc_topology_diff_t *diff)
    Compute the difference between 2 topologies.
    -
    hwloc_topology_diff_export_xmlbuffer
    int hwloc_topology_diff_export_xmlbuffer(hwloc_topology_diff_t diff, const char *refname, char **xmlbuffer, int *buflen)
    Export a list of topology differences to a XML buffer.
    -
    hwloc_topology_diff_load_xmlbuffer
    int hwloc_topology_diff_load_xmlbuffer(const char *xmlbuffer, int buflen, hwloc_topology_diff_t *diff, char **refname)
    Load a list of topology differences from a XML buffer.
    -
    hwloc_topology_diff_apply_flags_e
    hwloc_topology_diff_apply_flags_e
    Flags to be given to hwloc_topology_diff_apply().
    Definition: diff.h:198
    -
    hwloc_topology_diff_apply
    int hwloc_topology_diff_apply(hwloc_topology_t topology, hwloc_topology_diff_t diff, unsigned long flags)
    Apply a topology diff to an existing topology.
    -
    HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX
    @ HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX
    The difference is too complex, it cannot be represented. The difference below this object has not bee...
    Definition: diff.h:124
    -
    HWLOC_TOPOLOGY_DIFF_OBJ_ATTR
    @ HWLOC_TOPOLOGY_DIFF_OBJ_ATTR
    An object attribute was changed. The union is a hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s...
    Definition: diff.h:115
    -
    HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_INFO
    @ HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_INFO
    the value of an info attribute is modified. The union is a hwloc_topology_diff_obj_attr_u::hwloc_topo...
    Definition: diff.h:78
    -
    HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_NAME
    @ HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_NAME
    The object name is modified. The union is a hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_a...
    Definition: diff.h:74
    -
    HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_SIZE
    @ HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_SIZE
    The object local memory is modified. The union is a hwloc_topology_diff_obj_attr_u::hwloc_topology_di...
    Definition: diff.h:67
    -
    HWLOC_TOPOLOGY_DIFF_APPLY_REVERSE
    @ HWLOC_TOPOLOGY_DIFF_APPLY_REVERSE
    Apply topology diff in reverse direction.
    Definition: diff.h:202
    -
    hwloc_topology_diff_obj_attr_u
    One object attribute difference.
    Definition: diff.h:83
    -
    hwloc_topology_diff_obj_attr_u::string
    struct hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s string
    -
    hwloc_topology_diff_obj_attr_u::uint64
    struct hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s uint64
    - -
    hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_generic_s::type
    hwloc_topology_diff_obj_attr_type_t type
    Definition: diff.h:86
    -
    hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s
    Integer attribute modification with an optional index.
    Definition: diff.h:90
    - - - -
    hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s::type
    hwloc_topology_diff_obj_attr_type_t type
    Definition: diff.h:92
    -
    hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s
    String attribute modification with an optional name.
    Definition: diff.h:99
    - - -
    hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s::type
    hwloc_topology_diff_obj_attr_type_t type
    Definition: diff.h:101
    - -
    hwloc_topology_diff_u
    One element of a difference list between two topologies.
    Definition: diff.h:129
    - -
    hwloc_topology_diff_u::hwloc_topology_diff_generic_s::type
    hwloc_topology_diff_type_t type
    Definition: diff.h:132
    -
    hwloc_topology_diff_u::hwloc_topology_diff_generic_s::next
    union hwloc_topology_diff_u * next
    Definition: diff.h:133
    - -
    hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s::type
    hwloc_topology_diff_type_t type
    Definition: diff.h:138
    - -
    hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s::diff
    union hwloc_topology_diff_obj_attr_u diff
    Definition: diff.h:143
    -
    hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s::next
    union hwloc_topology_diff_u * next
    Definition: diff.h:139
    - - -
    hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s::next
    union hwloc_topology_diff_u * next
    Definition: diff.h:149
    - -
    hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s::type
    hwloc_topology_diff_type_t type
    Definition: diff.h:148
    - -
    - - - - - - - - -
    -
    shmem.h
    -
    -
    -
    1/*
    -
    2 * Copyright © 2013-2023 Inria. All rights reserved.
    -
    3 * See COPYING in top-level directory.
    -
    4 */
    -
    5
    -
    10#ifndef HWLOC_SHMEM_H
    -
    11#define HWLOC_SHMEM_H
    -
    12
    -
    13#include "hwloc.h"
    -
    14
    -
    15#ifdef __cplusplus
    -
    16extern "C" {
    -
    17#elif 0
    -
    18}
    -
    19#endif
    -
    20
    -
    21
    -
    55HWLOC_DECLSPEC int hwloc_shmem_topology_get_length(hwloc_topology_t topology,
    -
    56 size_t *lengthp,
    -
    57 unsigned long flags);
    -
    58
    -
    85HWLOC_DECLSPEC int hwloc_shmem_topology_write(hwloc_topology_t topology,
    -
    86 int fd, hwloc_uint64_t fileoffset,
    -
    87 void *mmap_address, size_t length,
    -
    88 unsigned long flags);
    -
    89
    -
    130HWLOC_DECLSPEC int hwloc_shmem_topology_adopt(hwloc_topology_t *topologyp,
    -
    131 int fd, hwloc_uint64_t fileoffset,
    -
    132 void *mmap_address, size_t length,
    -
    133 unsigned long flags);
    -
    137#ifdef __cplusplus
    -
    138} /* extern "C" */
    -
    139#endif
    -
    140
    -
    141
    -
    142#endif /* HWLOC_SHMEM_H */
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:716
    -
    hwloc_shmem_topology_adopt
    int hwloc_shmem_topology_adopt(hwloc_topology_t *topologyp, int fd, hwloc_uint64_t fileoffset, void *mmap_address, size_t length, unsigned long flags)
    Adopt a shared memory topology stored in a file.
    -
    hwloc_shmem_topology_write
    int hwloc_shmem_topology_write(hwloc_topology_t topology, int fd, hwloc_uint64_t fileoffset, void *mmap_address, size_t length, unsigned long flags)
    Duplicate a topology to a shared memory file.
    -
    hwloc_shmem_topology_get_length
    int hwloc_shmem_topology_get_length(hwloc_topology_t topology, size_t *lengthp, unsigned long flags)
    Get the required shared memory length for storing a topology.
    -
    - - - - - - - - -
    -
    plugins.h
    -
    -
    -
    1/*
    -
    2 * Copyright © 2013-2022 Inria. All rights reserved.
    -
    3 * Copyright © 2016 Cisco Systems, Inc. All rights reserved.
    -
    4 * See COPYING in top-level directory.
    -
    5 */
    -
    6
    -
    7#ifndef HWLOC_PLUGINS_H
    -
    8#define HWLOC_PLUGINS_H
    -
    9
    -
    14struct hwloc_backend;
    -
    15
    -
    16#include "hwloc.h"
    -
    17
    -
    18#ifdef HWLOC_INSIDE_PLUGIN
    -
    19/* needed for hwloc_plugin_check_namespace() */
    -
    20#ifdef HWLOC_HAVE_LTDL
    -
    21#include <ltdl.h>
    -
    22#else
    -
    23#include <dlfcn.h>
    -
    24#endif
    -
    25#endif
    -
    26
    -
    27
    -
    28
    -
    41struct hwloc_disc_component {
    -
    45 const char *name;
    -
    46
    -
    50 unsigned phases;
    -
    51
    -
    60 unsigned excluded_phases;
    -
    61
    -
    65 struct hwloc_backend * (*instantiate)(struct hwloc_topology *topology, struct hwloc_disc_component *component, unsigned excluded_phases, const void *data1, const void *data2, const void *data3);
    -
    66
    -
    79 unsigned priority;
    -
    80
    -
    84 unsigned enabled_by_default;
    -
    85
    -
    90 struct hwloc_disc_component * next;
    -
    91};
    -
    92
    -
    106typedef enum hwloc_disc_phase_e {
    -
    111 HWLOC_DISC_PHASE_GLOBAL = (1U<<0),
    -
    112
    -
    115 HWLOC_DISC_PHASE_CPU = (1U<<1),
    -
    116
    -
    119 HWLOC_DISC_PHASE_MEMORY = (1U<<2),
    -
    120
    -
    123 HWLOC_DISC_PHASE_PCI = (1U<<3),
    -
    124
    -
    127 HWLOC_DISC_PHASE_IO = (1U<<4),
    -
    128
    -
    131 HWLOC_DISC_PHASE_MISC = (1U<<5),
    -
    132
    -
    135 HWLOC_DISC_PHASE_ANNOTATE = (1U<<6),
    -
    136
    -
    142 HWLOC_DISC_PHASE_TWEAK = (1U<<7)
    -
    143} hwloc_disc_phase_t;
    -
    144
    -
    146enum hwloc_disc_status_flag_e {
    -
    148 HWLOC_DISC_STATUS_FLAG_GOT_ALLOWED_RESOURCES = (1UL<<1)
    -
    149};
    -
    150
    -
    156struct hwloc_disc_status {
    -
    160 hwloc_disc_phase_t phase;
    -
    161
    -
    165 unsigned excluded_phases;
    -
    166
    -
    168 unsigned long flags;
    -
    169};
    -
    170
    -
    189struct hwloc_backend {
    -
    191 struct hwloc_disc_component * component;
    -
    193 struct hwloc_topology * topology;
    -
    195 int envvar_forced;
    -
    197 struct hwloc_backend * next;
    -
    198
    -
    202 unsigned phases;
    -
    203
    -
    205 unsigned long flags;
    -
    206
    -
    213 int is_thissystem;
    -
    214
    -
    216 void * private_data;
    -
    220 void (*disable)(struct hwloc_backend *backend);
    -
    221
    -
    227 int (*discover)(struct hwloc_backend *backend, struct hwloc_disc_status *status);
    -
    228
    -
    233 int (*get_pci_busid_cpuset)(struct hwloc_backend *backend, struct hwloc_pcidev_attr_s *busid, hwloc_bitmap_t cpuset);
    -
    234};
    -
    235
    -
    239HWLOC_DECLSPEC struct hwloc_backend * hwloc_backend_alloc(struct hwloc_topology *topology, struct hwloc_disc_component *component);
    -
    240
    -
    242HWLOC_DECLSPEC int hwloc_backend_enable(struct hwloc_backend *backend);
    -
    243
    -
    257typedef enum hwloc_component_type_e {
    -
    259 HWLOC_COMPONENT_TYPE_DISC,
    -
    260
    -
    262 HWLOC_COMPONENT_TYPE_XML
    -
    263} hwloc_component_type_t;
    -
    264
    -
    270struct hwloc_component {
    -
    272 unsigned abi;
    -
    273
    -
    291 int (*init)(unsigned long flags);
    -
    292
    -
    304 void (*finalize)(unsigned long flags);
    -
    305
    -
    307 hwloc_component_type_t type;
    -
    308
    -
    310 unsigned long flags;
    -
    311
    -
    313 void * data;
    -
    314};
    -
    315
    -
    345HWLOC_DECLSPEC int hwloc_hide_errors(void);
    -
    346
    -
    347#define HWLOC_SHOW_CRITICAL_ERRORS() (hwloc_hide_errors() < 2)
    -
    348#define HWLOC_SHOW_ALL_ERRORS() (hwloc_hide_errors() == 0)
    -
    349
    -
    378HWLOC_DECLSPEC hwloc_obj_t
    -
    379hwloc__insert_object_by_cpuset(struct hwloc_topology *topology, hwloc_obj_t root,
    -
    380 hwloc_obj_t obj, const char *reason);
    -
    381
    -
    398HWLOC_DECLSPEC void hwloc_insert_object_by_parent(struct hwloc_topology *topology, hwloc_obj_t parent, hwloc_obj_t obj);
    -
    399
    -
    404HWLOC_DECLSPEC hwloc_obj_t hwloc_alloc_setup_object(hwloc_topology_t topology, hwloc_obj_type_t type, unsigned os_index);
    -
    405
    -
    414HWLOC_DECLSPEC int hwloc_obj_add_children_sets(hwloc_obj_t obj);
    -
    415
    -
    423HWLOC_DECLSPEC int hwloc_topology_reconnect(hwloc_topology_t topology, unsigned long flags __hwloc_attribute_unused);
    -
    424
    -
    446static __hwloc_inline int
    -
    447hwloc_plugin_check_namespace(const char *pluginname __hwloc_attribute_unused, const char *symbol __hwloc_attribute_unused)
    -
    448{
    -
    449#ifdef HWLOC_INSIDE_PLUGIN
    -
    450 void *sym;
    -
    451#ifdef HWLOC_HAVE_LTDL
    -
    452 lt_dlhandle handle = lt_dlopen(NULL);
    -
    453#else
    -
    454 void *handle = dlopen(NULL, RTLD_NOW|RTLD_LOCAL);
    -
    455#endif
    -
    456 if (!handle)
    -
    457 /* cannot check, assume things will work */
    -
    458 return 0;
    -
    459#ifdef HWLOC_HAVE_LTDL
    -
    460 sym = lt_dlsym(handle, symbol);
    -
    461 lt_dlclose(handle);
    -
    462#else
    -
    463 sym = dlsym(handle, symbol);
    -
    464 dlclose(handle);
    -
    465#endif
    -
    466 if (!sym) {
    -
    467 static int verboseenv_checked = 0;
    -
    468 static int verboseenv_value = 0;
    -
    469 if (!verboseenv_checked) {
    -
    470 const char *verboseenv = getenv("HWLOC_PLUGINS_VERBOSE");
    -
    471 verboseenv_value = verboseenv ? atoi(verboseenv) : 0;
    -
    472 verboseenv_checked = 1;
    -
    473 }
    -
    474 if (verboseenv_value)
    -
    475 fprintf(stderr, "Plugin `%s' disabling itself because it cannot find the `%s' core symbol.\n",
    -
    476 pluginname, symbol);
    -
    477 return -1;
    -
    478 }
    -
    479#endif /* HWLOC_INSIDE_PLUGIN */
    -
    480 return 0;
    -
    481}
    -
    482
    -
    499static __hwloc_inline int
    -
    500hwloc_filter_check_pcidev_subtype_important(unsigned classid)
    -
    501{
    -
    502 unsigned baseclass = classid >> 8;
    -
    503 return (baseclass == 0x03 /* PCI_BASE_CLASS_DISPLAY */
    -
    504 || baseclass == 0x02 /* PCI_BASE_CLASS_NETWORK */
    -
    505 || baseclass == 0x01 /* PCI_BASE_CLASS_STORAGE */
    -
    506 || baseclass == 0x00 /* Unclassified, for Atos/Bull BXI */
    -
    507 || baseclass == 0x0b /* PCI_BASE_CLASS_PROCESSOR */
    -
    508 || classid == 0x0c04 /* PCI_CLASS_SERIAL_FIBER */
    -
    509 || classid == 0x0c06 /* PCI_CLASS_SERIAL_INFINIBAND */
    -
    510 || classid == 0x0502 /* PCI_CLASS_MEMORY_CXL */
    -
    511 || baseclass == 0x06 /* PCI_BASE_CLASS_BRIDGE with non-PCI downstream. the core will drop the useless ones later */
    -
    512 || baseclass == 0x12 /* Processing Accelerators */);
    -
    513}
    -
    514
    -
    519static __hwloc_inline int
    -
    520hwloc_filter_check_osdev_subtype_important(hwloc_obj_osdev_type_t subtype)
    -
    521{
    -
    522 return (subtype != HWLOC_OBJ_OSDEV_DMA);
    -
    523}
    -
    524
    -
    531static __hwloc_inline int
    -
    532hwloc_filter_check_keep_object_type(hwloc_topology_t topology, hwloc_obj_type_t type)
    -
    533{
    -
    534 enum hwloc_type_filter_e filter = HWLOC_TYPE_FILTER_KEEP_NONE;
    -
    535 hwloc_topology_get_type_filter(topology, type, &filter);
    -
    536 assert(filter != HWLOC_TYPE_FILTER_KEEP_IMPORTANT); /* IMPORTANT only used for I/O */
    -
    537 return filter == HWLOC_TYPE_FILTER_KEEP_NONE ? 0 : 1;
    -
    538}
    -
    539
    -
    544static __hwloc_inline int
    -
    545hwloc_filter_check_keep_object(hwloc_topology_t topology, hwloc_obj_t obj)
    -
    546{
    -
    547 hwloc_obj_type_t type = obj->type;
    -
    548 enum hwloc_type_filter_e filter = HWLOC_TYPE_FILTER_KEEP_NONE;
    -
    549 hwloc_topology_get_type_filter(topology, type, &filter);
    -
    550 if (filter == HWLOC_TYPE_FILTER_KEEP_NONE)
    -
    551 return 0;
    -
    552 if (filter == HWLOC_TYPE_FILTER_KEEP_IMPORTANT) {
    -
    553 if (type == HWLOC_OBJ_PCI_DEVICE)
    -
    554 return hwloc_filter_check_pcidev_subtype_important(obj->attr->pcidev.class_id);
    -
    555 if (type == HWLOC_OBJ_OS_DEVICE)
    -
    556 return hwloc_filter_check_osdev_subtype_important(obj->attr->osdev.type);
    -
    557 }
    -
    558 return 1;
    -
    559}
    -
    560
    -
    577HWLOC_DECLSPEC unsigned hwloc_pcidisc_find_cap(const unsigned char *config, unsigned cap);
    -
    578
    -
    584HWLOC_DECLSPEC int hwloc_pcidisc_find_linkspeed(const unsigned char *config, unsigned offset, float *linkspeed);
    -
    585
    -
    590HWLOC_DECLSPEC hwloc_obj_type_t hwloc_pcidisc_check_bridge_type(unsigned device_class, const unsigned char *config);
    -
    591
    -
    598HWLOC_DECLSPEC int hwloc_pcidisc_find_bridge_buses(unsigned domain, unsigned bus, unsigned dev, unsigned func,
    -
    599 unsigned *secondary_busp, unsigned *subordinate_busp,
    -
    600 const unsigned char *config);
    -
    601
    -
    606HWLOC_DECLSPEC void hwloc_pcidisc_tree_insert_by_busid(struct hwloc_obj **treep, struct hwloc_obj *obj);
    -
    607
    -
    613HWLOC_DECLSPEC int hwloc_pcidisc_tree_attach(struct hwloc_topology *topology, struct hwloc_obj *tree);
    -
    614
    -
    638HWLOC_DECLSPEC struct hwloc_obj * hwloc_pci_find_parent_by_busid(struct hwloc_topology *topology, unsigned domain, unsigned bus, unsigned dev, unsigned func);
    -
    639
    -
    646HWLOC_DECLSPEC struct hwloc_obj * hwloc_pci_find_by_busid(struct hwloc_topology *topology, unsigned domain, unsigned bus, unsigned dev, unsigned func);
    -
    647
    -
    649typedef void * hwloc_backend_distances_add_handle_t;
    -
    650
    -
    657HWLOC_DECLSPEC hwloc_backend_distances_add_handle_t
    -
    658hwloc_backend_distances_add_create(hwloc_topology_t topology,
    -
    659 const char *name, unsigned long kind,
    -
    660 unsigned long flags);
    -
    661
    -
    673HWLOC_DECLSPEC int
    -
    674hwloc_backend_distances_add_values(hwloc_topology_t topology,
    -
    675 hwloc_backend_distances_add_handle_t handle,
    -
    676 unsigned nbobjs, hwloc_obj_t *objs,
    -
    677 hwloc_uint64_t *values,
    -
    678 unsigned long flags);
    -
    679
    -
    686HWLOC_DECLSPEC int
    -
    687hwloc_backend_distances_add_commit(hwloc_topology_t topology,
    -
    688 hwloc_backend_distances_add_handle_t handle,
    -
    689 unsigned long flags);
    -
    690
    -
    696#endif /* HWLOC_PLUGINS_H */
    -
    hwloc_obj_osdev_type_t
    enum hwloc_obj_osdev_type_e hwloc_obj_osdev_type_t
    Type of a OS device.
    -
    hwloc_obj_type_t
    hwloc_obj_type_t
    Type of topology object.
    Definition: hwloc.h:197
    -
    HWLOC_OBJ_OSDEV_DMA
    @ HWLOC_OBJ_OSDEV_DMA
    Operating system dma engine device. For instance the "dma0chan0" DMA channel on Linux.
    Definition: hwloc.h:372
    -
    HWLOC_OBJ_OS_DEVICE
    @ HWLOC_OBJ_OS_DEVICE
    Operating system device (filtered out by default).
    Definition: hwloc.h:300
    -
    HWLOC_OBJ_PCI_DEVICE
    @ HWLOC_OBJ_PCI_DEVICE
    PCI device (filtered out by default).
    Definition: hwloc.h:290
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:716
    -
    hwloc_topology_get_type_filter
    int hwloc_topology_get_type_filter(hwloc_topology_t topology, hwloc_obj_type_t type, enum hwloc_type_filter_e *filter)
    Get the current filtering for the given object type.
    -
    hwloc_type_filter_e
    hwloc_type_filter_e
    Type filtering flags.
    Definition: hwloc.h:2365
    -
    HWLOC_TYPE_FILTER_KEEP_NONE
    @ HWLOC_TYPE_FILTER_KEEP_NONE
    Ignore all objects of this type.
    Definition: hwloc.h:2379
    -
    HWLOC_TYPE_FILTER_KEEP_IMPORTANT
    @ HWLOC_TYPE_FILTER_KEEP_IMPORTANT
    Only keep likely-important objects of the given type.
    Definition: hwloc.h:2408
    -
    hwloc_bitmap_t
    struct hwloc_bitmap_s * hwloc_bitmap_t
    Set of bits represented as an opaque pointer to an internal bitmap.
    Definition: bitmap.h:69
    -
    hwloc_backend_enable
    int hwloc_backend_enable(struct hwloc_backend *backend)
    Enable a previously allocated and setup backend.
    -
    hwloc_disc_phase_t
    enum hwloc_disc_phase_e hwloc_disc_phase_t
    Discovery phase.
    -
    hwloc_backend_alloc
    struct hwloc_backend * hwloc_backend_alloc(struct hwloc_topology *topology, struct hwloc_disc_component *component)
    Allocate a backend structure, set good default values, initialize backend->component and topology,...
    -
    hwloc_disc_phase_e
    hwloc_disc_phase_e
    Discovery phase.
    Definition: plugins.h:106
    -
    hwloc_disc_status_flag_e
    hwloc_disc_status_flag_e
    Discovery status flags.
    Definition: plugins.h:146
    -
    HWLOC_DISC_PHASE_CPU
    @ HWLOC_DISC_PHASE_CPU
    CPU discovery.
    Definition: plugins.h:115
    -
    HWLOC_DISC_PHASE_PCI
    @ HWLOC_DISC_PHASE_PCI
    Attach PCI devices and bridges to existing CPU objects.
    Definition: plugins.h:123
    -
    HWLOC_DISC_PHASE_ANNOTATE
    @ HWLOC_DISC_PHASE_ANNOTATE
    Annotating existing objects, adding distances, etc.
    Definition: plugins.h:135
    -
    HWLOC_DISC_PHASE_MISC
    @ HWLOC_DISC_PHASE_MISC
    Misc objects that gets added below anything else.
    Definition: plugins.h:131
    -
    HWLOC_DISC_PHASE_IO
    @ HWLOC_DISC_PHASE_IO
    I/O discovery that requires PCI devices (OS devices such as OpenCL, CUDA, etc.).
    Definition: plugins.h:127
    -
    HWLOC_DISC_PHASE_GLOBAL
    @ HWLOC_DISC_PHASE_GLOBAL
    xml or synthetic, platform-specific components such as bgq. Discovers everything including CPU,...
    Definition: plugins.h:111
    -
    HWLOC_DISC_PHASE_MEMORY
    @ HWLOC_DISC_PHASE_MEMORY
    Attach memory to existing CPU objects.
    Definition: plugins.h:119
    -
    HWLOC_DISC_PHASE_TWEAK
    @ HWLOC_DISC_PHASE_TWEAK
    Final tweaks to a ready-to-use topology. This phase runs once the topology is loaded,...
    Definition: plugins.h:142
    -
    HWLOC_DISC_STATUS_FLAG_GOT_ALLOWED_RESOURCES
    @ HWLOC_DISC_STATUS_FLAG_GOT_ALLOWED_RESOURCES
    The sets of allowed resources were already retrieved.
    Definition: plugins.h:148
    -
    hwloc_component_type_t
    enum hwloc_component_type_e hwloc_component_type_t
    Generic component type.
    -
    hwloc_component_type_e
    hwloc_component_type_e
    Generic component type.
    Definition: plugins.h:257
    -
    HWLOC_COMPONENT_TYPE_DISC
    @ HWLOC_COMPONENT_TYPE_DISC
    The data field must point to a struct hwloc_disc_component.
    Definition: plugins.h:259
    -
    HWLOC_COMPONENT_TYPE_XML
    @ HWLOC_COMPONENT_TYPE_XML
    The data field must point to a struct hwloc_xml_component.
    Definition: plugins.h:262
    -
    hwloc_alloc_setup_object
    hwloc_obj_t hwloc_alloc_setup_object(hwloc_topology_t topology, hwloc_obj_type_t type, unsigned os_index)
    Allocate and initialize an object of the given type and physical index.
    -
    hwloc_insert_object_by_parent
    void hwloc_insert_object_by_parent(struct hwloc_topology *topology, hwloc_obj_t parent, hwloc_obj_t obj)
    Insert an object somewhere in the topology.
    -
    hwloc_topology_reconnect
    int hwloc_topology_reconnect(hwloc_topology_t topology, unsigned long flags)
    Request a reconnection of children and levels in the topology.
    -
    hwloc__insert_object_by_cpuset
    hwloc_obj_t hwloc__insert_object_by_cpuset(struct hwloc_topology *topology, hwloc_obj_t root, hwloc_obj_t obj, const char *reason)
    Add an object to the topology.
    -
    hwloc_obj_add_children_sets
    int hwloc_obj_add_children_sets(hwloc_obj_t obj)
    Setup object cpusets/nodesets by OR'ing its children.
    -
    hwloc_hide_errors
    int hwloc_hide_errors(void)
    Check whether error messages are hidden.
    -
    hwloc_plugin_check_namespace
    static int hwloc_plugin_check_namespace(const char *pluginname, const char *symbol)
    Make sure that plugins can lookup core symbols.
    Definition: plugins.h:447
    -
    hwloc_filter_check_keep_object_type
    static int hwloc_filter_check_keep_object_type(hwloc_topology_t topology, hwloc_obj_type_t type)
    Check whether a non-I/O object type should be filtered-out.
    Definition: plugins.h:532
    -
    hwloc_filter_check_keep_object
    static int hwloc_filter_check_keep_object(hwloc_topology_t topology, hwloc_obj_t obj)
    Check whether the given object should be filtered-out.
    Definition: plugins.h:545
    -
    hwloc_filter_check_pcidev_subtype_important
    static int hwloc_filter_check_pcidev_subtype_important(unsigned classid)
    Check whether the given PCI device classid is important.
    Definition: plugins.h:500
    -
    hwloc_filter_check_osdev_subtype_important
    static int hwloc_filter_check_osdev_subtype_important(hwloc_obj_osdev_type_t subtype)
    Check whether the given OS device subtype is important.
    Definition: plugins.h:520
    -
    hwloc_pcidisc_find_linkspeed
    int hwloc_pcidisc_find_linkspeed(const unsigned char *config, unsigned offset, float *linkspeed)
    Fill linkspeed by reading the PCI config space where PCI_CAP_ID_EXP is at position offset.
    -
    hwloc_pcidisc_check_bridge_type
    hwloc_obj_type_t hwloc_pcidisc_check_bridge_type(unsigned device_class, const unsigned char *config)
    Return the hwloc object type (PCI device or Bridge) for the given class and configuration space.
    -
    hwloc_pcidisc_find_cap
    unsigned hwloc_pcidisc_find_cap(const unsigned char *config, unsigned cap)
    Return the offset of the given capability in the PCI config space buffer.
    -
    hwloc_pcidisc_find_bridge_buses
    int hwloc_pcidisc_find_bridge_buses(unsigned domain, unsigned bus, unsigned dev, unsigned func, unsigned *secondary_busp, unsigned *subordinate_busp, const unsigned char *config)
    Fills the attributes of the given PCI bridge using the given PCI config space.
    -
    hwloc_pcidisc_tree_insert_by_busid
    void hwloc_pcidisc_tree_insert_by_busid(struct hwloc_obj **treep, struct hwloc_obj *obj)
    Insert a PCI object in the given PCI tree by looking at PCI bus IDs.
    -
    hwloc_pcidisc_tree_attach
    int hwloc_pcidisc_tree_attach(struct hwloc_topology *topology, struct hwloc_obj *tree)
    Add some hostbridges on top of the given tree of PCI objects and attach them to the topology.
    -
    hwloc_backend_distances_add_commit
    int hwloc_backend_distances_add_commit(hwloc_topology_t topology, hwloc_backend_distances_add_handle_t handle, unsigned long flags)
    Commit a new distances structure.
    -
    hwloc_pci_find_by_busid
    struct hwloc_obj * hwloc_pci_find_by_busid(struct hwloc_topology *topology, unsigned domain, unsigned bus, unsigned dev, unsigned func)
    Find the PCI device or bridge matching a PCI bus ID exactly.
    -
    hwloc_pci_find_parent_by_busid
    struct hwloc_obj * hwloc_pci_find_parent_by_busid(struct hwloc_topology *topology, unsigned domain, unsigned bus, unsigned dev, unsigned func)
    Find the object or a parent of a PCI bus ID.
    -
    hwloc_backend_distances_add_values
    int hwloc_backend_distances_add_values(hwloc_topology_t topology, hwloc_backend_distances_add_handle_t handle, unsigned nbobjs, hwloc_obj_t *objs, hwloc_uint64_t *values, unsigned long flags)
    Specify the objects and values in a new empty distances structure.
    -
    hwloc_backend_distances_add_create
    hwloc_backend_distances_add_handle_t hwloc_backend_distances_add_create(hwloc_topology_t topology, const char *name, unsigned long kind, unsigned long flags)
    Create a new empty distances structure.
    -
    hwloc_backend_distances_add_handle_t
    void * hwloc_backend_distances_add_handle_t
    Handle to a new distances structure during its addition to the topology.
    Definition: plugins.h:649
    -
    hwloc_obj
    Structure of a topology object.
    Definition: hwloc.h:420
    -
    hwloc_obj::name
    char * name
    Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name str...
    Definition: hwloc.h:432
    -
    hwloc_obj::type
    hwloc_obj_type_t type
    Type of object.
    Definition: hwloc.h:422
    -
    hwloc_obj::attr
    union hwloc_obj_attr_u * attr
    Object type-specific Attributes, may be NULL if no attribute value was found.
    Definition: hwloc.h:439
    -
    hwloc_obj_attr_u::pcidev
    struct hwloc_obj_attr_u::hwloc_pcidev_attr_s pcidev
    -
    hwloc_obj_attr_u::osdev
    struct hwloc_obj_attr_u::hwloc_osdev_attr_s osdev
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s::class_id
    unsigned short class_id
    Definition: hwloc.h:664
    -
    hwloc_obj_attr_u::hwloc_osdev_attr_s::type
    hwloc_obj_osdev_type_t type
    Definition: hwloc.h:690
    -
    hwloc_disc_component
    Discovery component structure.
    Definition: plugins.h:41
    -
    hwloc_disc_component::name
    const char * name
    Name. If this component is built as a plugin, this name does not have to match the plugin filename.
    Definition: plugins.h:45
    -
    hwloc_disc_component::phases
    unsigned phases
    Discovery phases performed by this component. OR'ed set of hwloc_disc_phase_t.
    Definition: plugins.h:50
    -
    hwloc_disc_component::excluded_phases
    unsigned excluded_phases
    Component phases to exclude, as an OR'ed set of hwloc_disc_phase_t.
    Definition: plugins.h:60
    -
    hwloc_disc_component::enabled_by_default
    unsigned enabled_by_default
    Enabled by default. If unset, if will be disabled unless explicitly requested.
    Definition: plugins.h:84
    -
    hwloc_disc_component::priority
    unsigned priority
    Component priority. Used to sort topology->components, higher priority first. Also used to decide bet...
    Definition: plugins.h:79
    -
    hwloc_disc_status
    Discovery status structure.
    Definition: plugins.h:156
    -
    hwloc_disc_status::excluded_phases
    unsigned excluded_phases
    Dynamically excluded phases. If a component decides during discovery that some phases are no longer n...
    Definition: plugins.h:165
    -
    hwloc_disc_status::phase
    hwloc_disc_phase_t phase
    The current discovery phase that is performed. Must match one of the phases in the component phases f...
    Definition: plugins.h:160
    -
    hwloc_disc_status::flags
    unsigned long flags
    OR'ed set of hwloc_disc_status_flag_e.
    Definition: plugins.h:168
    -
    hwloc_backend
    Discovery backend structure.
    Definition: plugins.h:189
    -
    hwloc_backend::private_data
    void * private_data
    Backend private data, or NULL if none.
    Definition: plugins.h:216
    -
    hwloc_backend::disable
    void(* disable)(struct hwloc_backend *backend)
    Callback for freeing the private_data. May be NULL.
    Definition: plugins.h:220
    -
    hwloc_backend::flags
    unsigned long flags
    Backend flags, currently always 0.
    Definition: plugins.h:205
    -
    hwloc_backend::get_pci_busid_cpuset
    int(* get_pci_busid_cpuset)(struct hwloc_backend *backend, struct hwloc_pcidev_attr_s *busid, hwloc_bitmap_t cpuset)
    Callback to retrieve the locality of a PCI object. Called by the PCI core when attaching PCI hierarch...
    Definition: plugins.h:233
    -
    hwloc_backend::is_thissystem
    int is_thissystem
    Backend-specific 'is_thissystem' property. Set to 0 if the backend disables the thissystem flag for t...
    Definition: plugins.h:213
    -
    hwloc_backend::discover
    int(* discover)(struct hwloc_backend *backend, struct hwloc_disc_status *status)
    Main discovery callback. returns -1 on error, either because it couldn't add its objects ot the exist...
    Definition: plugins.h:227
    -
    hwloc_backend::phases
    unsigned phases
    Discovery phases performed by this component, possibly without some of them if excluded by other comp...
    Definition: plugins.h:202
    -
    hwloc_component
    Generic component structure.
    Definition: plugins.h:270
    -
    hwloc_component::abi
    unsigned abi
    Component ABI version, set to HWLOC_COMPONENT_ABI.
    Definition: plugins.h:272
    -
    hwloc_component::finalize
    void(* finalize)(unsigned long flags)
    Process-wide component termination callback.
    Definition: plugins.h:304
    -
    hwloc_component::data
    void * data
    Component data, pointing to a struct hwloc_disc_component or struct hwloc_xml_component.
    Definition: plugins.h:313
    -
    hwloc_component::type
    hwloc_component_type_t type
    Component type.
    Definition: plugins.h:307
    -
    hwloc_component::flags
    unsigned long flags
    Component flags, unused for now.
    Definition: plugins.h:310
    -
    hwloc_component::init
    int(* init)(unsigned long flags)
    Process-wide component initialization callback.
    Definition: plugins.h:291
    -
    - - - - - - - - -
    -
    netloc.h
    -
    -
    -
    1/*
    -
    2 * Copyright © 2013-2014 Cisco Systems, Inc. All rights reserved.
    -
    3 * Copyright © 2013-2014 University of Wisconsin-La Crosse.
    -
    4 * All rights reserved.
    -
    5 * Copyright © 2015-2016 Inria. All rights reserved.
    -
    6 *
    -
    7 * $COPYRIGHT$
    -
    8 *
    -
    9 * Additional copyrights may follow
    -
    10 * See COPYING in top-level directory.
    -
    11 *
    -
    12 * $HEADER$
    -
    13 */
    -
    14
    -
    15#ifndef _NETLOC_H_
    -
    16#define _NETLOC_H_
    -
    17
    -
    18#ifndef _GNU_SOURCE
    -
    19#define _GNU_SOURCE // for asprintf
    -
    20#endif
    -
    21
    -
    22#include <hwloc/autogen/config.h>
    -
    23
    -
    24#include <hwloc.h>
    -
    25
    -
    26#ifdef __cplusplus
    -
    27extern "C" {
    -
    28#endif
    -
    29
    -
    36enum {
    -
    37 NETLOC_SUCCESS = 0,
    -
    38 NETLOC_ERROR = -1,
    -
    39 NETLOC_ERROR_NOTDIR = -2,
    -
    40 NETLOC_ERROR_NOENT = -3,
    -
    41 NETLOC_ERROR_EMPTY = -4,
    -
    42 NETLOC_ERROR_MULTIPLE = -5,
    -
    43 NETLOC_ERROR_NOT_IMPL = -6,
    -
    44 NETLOC_ERROR_EXISTS = -7,
    -
    45 NETLOC_ERROR_NOT_FOUND = -8,
    -
    46 NETLOC_ERROR_MAX = -9
    -
    47};
    -
    48
    -
    49
    -
    50#ifdef __cplusplus
    -
    51} /* extern "C" */
    -
    52#endif
    -
    53
    -
    56#endif // _NETLOC_H_
    -
    NETLOC_ERROR_EMPTY
    @ NETLOC_ERROR_EMPTY
    Definition: netloc.h:41
    -
    NETLOC_ERROR_MAX
    @ NETLOC_ERROR_MAX
    Definition: netloc.h:46
    -
    NETLOC_ERROR_MULTIPLE
    @ NETLOC_ERROR_MULTIPLE
    Definition: netloc.h:42
    -
    NETLOC_ERROR_NOT_IMPL
    @ NETLOC_ERROR_NOT_IMPL
    Definition: netloc.h:43
    -
    NETLOC_ERROR
    @ NETLOC_ERROR
    Definition: netloc.h:38
    -
    NETLOC_SUCCESS
    @ NETLOC_SUCCESS
    Definition: netloc.h:37
    -
    NETLOC_ERROR_NOT_FOUND
    @ NETLOC_ERROR_NOT_FOUND
    Definition: netloc.h:45
    -
    NETLOC_ERROR_EXISTS
    @ NETLOC_ERROR_EXISTS
    Definition: netloc.h:44
    -
    NETLOC_ERROR_NOTDIR
    @ NETLOC_ERROR_NOTDIR
    Definition: netloc.h:39
    -
    NETLOC_ERROR_NOENT
    @ NETLOC_ERROR_NOENT
    Definition: netloc.h:40
    -
    - - - - - - - -
    -
    Error reporting in the API
    -
    -
    -

    Most functions in the hwloc API return an integer value. Unless documentated differently, they return 0 on success and -1 on error. Functions that return a pointer type return NULL on error.

    -

    errno will be set to a meaningful value whenever possible. This includes the usual EINVAL when invalid function parameters are passed or ENOMEM when an internal allocation fails. Some specific errno value are also used, for instance for binding errors as documented in CPU binding.

    -

    Some modules describe return values of their functions in their introduction, for instance in The bitmap API.

    -
    - - - - - - - -
    -
    -Macros | -Functions
    -
    API version
    -
    -
    - - - - - - -

    -Macros

    #define HWLOC_API_VERSION   0x00020800
     
    #define HWLOC_COMPONENT_ABI   7
     
    - - - -

    -Functions

    unsigned hwloc_get_api_version (void)
     
    -

    Detailed Description

    -

    Macro Definition Documentation

    - -

    ◆ HWLOC_API_VERSION

    - -
    -
    - - - - -
    #define HWLOC_API_VERSION   0x00020800
    -
    - -

    Indicate at build time which hwloc API version is being used.

    -

    This number is updated to (X<<16)+(Y<<8)+Z when a new release X.Y.Z actually modifies the API.

    -

    Users may check for available features at build time using this number (see How do I handle API changes?).

    -
    Note
    This should not be confused with HWLOC_VERSION, the library version. Two stable releases of the same series usually have the same HWLOC_API_VERSION even if their HWLOC_VERSION are different.
    - -
    -
    - -

    ◆ HWLOC_COMPONENT_ABI

    - -
    -
    - - - - -
    #define HWLOC_COMPONENT_ABI   7
    -
    - -

    Current component and plugin ABI version (see hwloc/plugins.h)

    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_get_api_version()

    - -
    -
    - - - - - - - - -
    unsigned hwloc_get_api_version (void )
    -
    - -

    Indicate at runtime which hwloc API version was used at build time.

    -

    Should be HWLOC_API_VERSION if running on the same version.

    -
    Returns
    the build-time version number.
    - -
    -
    -
    - - - - - - - -
    -
    -Typedefs
    -
    Object Sets (hwloc_cpuset_t and hwloc_nodeset_t)
    -
    -
    - - - - - - - - - - -

    -Typedefs

    typedef hwloc_bitmap_t hwloc_cpuset_t
     
    typedef hwloc_const_bitmap_t hwloc_const_cpuset_t
     
    typedef hwloc_bitmap_t hwloc_nodeset_t
     
    typedef hwloc_const_bitmap_t hwloc_const_nodeset_t
     
    -

    Detailed Description

    -

    Hwloc uses bitmaps to represent two distinct kinds of object sets: CPU sets (hwloc_cpuset_t) and NUMA node sets (hwloc_nodeset_t). These types are both typedefs to a common back end type (hwloc_bitmap_t), and therefore all the hwloc bitmap functions are applicable to both hwloc_cpuset_t and hwloc_nodeset_t (see The bitmap API).

    -

    The rationale for having two different types is that even though the actions one wants to perform on these types are the same (e.g., enable and disable individual items in the set/mask), they're used in very different contexts: one for specifying which processors to use and one for specifying which NUMA nodes to use. Hence, the name difference is really just to reflect the intent of where the type is used.

    -

    Typedef Documentation

    - -

    ◆ hwloc_const_cpuset_t

    - -
    -
    - - - - -
    typedef hwloc_const_bitmap_t hwloc_const_cpuset_t
    -
    - -

    A non-modifiable hwloc_cpuset_t.

    - -
    -
    - -

    ◆ hwloc_const_nodeset_t

    - -
    -
    - - - - -
    typedef hwloc_const_bitmap_t hwloc_const_nodeset_t
    -
    - -

    A non-modifiable hwloc_nodeset_t.

    - -
    -
    - -

    ◆ hwloc_cpuset_t

    - -
    -
    - - - - -
    typedef hwloc_bitmap_t hwloc_cpuset_t
    -
    - -

    A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.

    -

    It may be consulted and modified with the bitmap API as any hwloc_bitmap_t (see hwloc/bitmap.h).

    -

    Each bit may be converted into a PU object using hwloc_get_pu_obj_by_os_index().

    - -
    -
    - -

    ◆ hwloc_nodeset_t

    - -
    -
    - - - - -
    typedef hwloc_bitmap_t hwloc_nodeset_t
    -
    - -

    A node set is a bitmap whose bits are set according to NUMA memory node physical OS indexes.

    -

    It may be consulted and modified with the bitmap API as any hwloc_bitmap_t (see hwloc/bitmap.h). Each bit may be converted into a NUMA node object using hwloc_get_numanode_obj_by_os_index().

    -

    When binding memory on a system without any NUMA node, the single main memory bank is considered as NUMA node #0.

    -

    See also Converting between CPU sets and node sets.

    - -
    -
    -
    - - - - - - - -
    -
    -Macros | -Typedefs | -Enumerations | -Functions
    -
    Object Types
    -
    -
    - - - - -

    -Macros

    #define HWLOC_TYPE_UNORDERED
     
    - - - - - - - -

    -Typedefs

    typedef enum hwloc_obj_cache_type_e hwloc_obj_cache_type_t
     
    typedef enum hwloc_obj_bridge_type_e hwloc_obj_bridge_type_t
     
    typedef enum hwloc_obj_osdev_type_e hwloc_obj_osdev_type_t
     
    - - - - - - - - - -

    -Enumerations

    enum  hwloc_obj_type_t {
    -  HWLOC_OBJ_MACHINE -, HWLOC_OBJ_PACKAGE -, HWLOC_OBJ_CORE -, HWLOC_OBJ_PU -,
    -  HWLOC_OBJ_L1CACHE -, HWLOC_OBJ_L2CACHE -, HWLOC_OBJ_L3CACHE -, HWLOC_OBJ_L4CACHE -,
    -  HWLOC_OBJ_L5CACHE -, HWLOC_OBJ_L1ICACHE -, HWLOC_OBJ_L2ICACHE -, HWLOC_OBJ_L3ICACHE -,
    -  HWLOC_OBJ_GROUP -, HWLOC_OBJ_NUMANODE -, HWLOC_OBJ_BRIDGE -, HWLOC_OBJ_PCI_DEVICE -,
    -  HWLOC_OBJ_OS_DEVICE -, HWLOC_OBJ_MISC -, HWLOC_OBJ_MEMCACHE -, HWLOC_OBJ_DIE -,
    -  HWLOC_OBJ_TYPE_MAX -
    - }
     
    enum  hwloc_obj_cache_type_e { HWLOC_OBJ_CACHE_UNIFIED -, HWLOC_OBJ_CACHE_DATA -, HWLOC_OBJ_CACHE_INSTRUCTION - }
     
    enum  hwloc_obj_bridge_type_e { HWLOC_OBJ_BRIDGE_HOST -, HWLOC_OBJ_BRIDGE_PCI - }
     
    enum  hwloc_obj_osdev_type_e {
    -  HWLOC_OBJ_OSDEV_BLOCK -, HWLOC_OBJ_OSDEV_GPU -, HWLOC_OBJ_OSDEV_NETWORK -, HWLOC_OBJ_OSDEV_OPENFABRICS -,
    -  HWLOC_OBJ_OSDEV_DMA -, HWLOC_OBJ_OSDEV_COPROC -
    - }
     
    - - - -

    -Functions

    int hwloc_compare_types (hwloc_obj_type_t type1, hwloc_obj_type_t type2)
     
    -

    Detailed Description

    -

    Macro Definition Documentation

    - -

    ◆ HWLOC_TYPE_UNORDERED

    - -
    -
    - - - - -
    #define HWLOC_TYPE_UNORDERED
    -
    - -

    Value returned by hwloc_compare_types() when types can not be compared.

    - -
    -
    -

    Typedef Documentation

    - -

    ◆ hwloc_obj_bridge_type_t

    - -
    -
    - - - - -
    typedef enum hwloc_obj_bridge_type_e hwloc_obj_bridge_type_t
    -
    - -

    Type of one side (upstream or downstream) of an I/O bridge.

    - -
    -
    - -

    ◆ hwloc_obj_cache_type_t

    - -
    -
    - - - - -
    typedef enum hwloc_obj_cache_type_e hwloc_obj_cache_type_t
    -
    - -

    Cache type.

    - -
    -
    - -

    ◆ hwloc_obj_osdev_type_t

    - -
    -
    - - - - -
    typedef enum hwloc_obj_osdev_type_e hwloc_obj_osdev_type_t
    -
    - -

    Type of a OS device.

    - -
    -
    -

    Enumeration Type Documentation

    - -

    ◆ hwloc_obj_bridge_type_e

    - -
    -
    - - - - -
    enum hwloc_obj_bridge_type_e
    -
    - -

    Type of one side (upstream or downstream) of an I/O bridge.

    - - - -
    Enumerator
    HWLOC_OBJ_BRIDGE_HOST 

    Host-side of a bridge, only possible upstream.

    -
    HWLOC_OBJ_BRIDGE_PCI 

    PCI-side of a bridge.

    -
    - -
    -
    - -

    ◆ hwloc_obj_cache_type_e

    - -
    -
    - - - - -
    enum hwloc_obj_cache_type_e
    -
    - -

    Cache type.

    - - - - -
    Enumerator
    HWLOC_OBJ_CACHE_UNIFIED 

    Unified cache.

    -
    HWLOC_OBJ_CACHE_DATA 

    Data cache.

    -
    HWLOC_OBJ_CACHE_INSTRUCTION 

    Instruction cache (filtered out by default).

    -
    - -
    -
    - -

    ◆ hwloc_obj_osdev_type_e

    - -
    -
    - - - - -
    enum hwloc_obj_osdev_type_e
    -
    - -

    Type of a OS device.

    - - - - - - - -
    Enumerator
    HWLOC_OBJ_OSDEV_BLOCK 

    Operating system block device, or non-volatile memory device. For instance "sda" or "dax2.0" on Linux.

    -
    HWLOC_OBJ_OSDEV_GPU 

    Operating system GPU device. For instance ":0.0" for a GL display, "card0" for a Linux DRM device.

    -
    HWLOC_OBJ_OSDEV_NETWORK 

    Operating system network device. For instance the "eth0" interface on Linux.

    -
    HWLOC_OBJ_OSDEV_OPENFABRICS 

    Operating system openfabrics device. For instance the "mlx4_0" InfiniBand HCA, "hfi1_0" Omni-Path interface, or "bxi0" Atos/Bull BXI HCA on Linux.

    -
    HWLOC_OBJ_OSDEV_DMA 

    Operating system dma engine device. For instance the "dma0chan0" DMA channel on Linux.

    -
    HWLOC_OBJ_OSDEV_COPROC 

    Operating system co-processor device. For instance "opencl0d0" for a OpenCL device, "cuda0" for a CUDA device.

    -
    - -
    -
    - -

    ◆ hwloc_obj_type_t

    - -
    -
    - - - - -
    enum hwloc_obj_type_t
    -
    - -

    Type of topology object.

    -
    Note
    Do not rely on the ordering or completeness of the values as new ones may be defined in the future! If you need to compare types, use hwloc_compare_types() instead.
    - - - - - - - - - - - - - - - - - - - - - -
    Enumerator
    HWLOC_OBJ_MACHINE 

    Machine. A set of processors and memory with cache coherency.

    -

    This type is always used for the root object of a topology, and never used anywhere else. Hence its parent is always NULL.

    -
    HWLOC_OBJ_PACKAGE 

    Physical package. The physical package that usually gets inserted into a socket on the motherboard. A processor package usually contains multiple cores, and possibly some dies.

    -
    HWLOC_OBJ_CORE 

    Core. A computation unit (may be shared by several PUs, aka logical processors).

    -
    HWLOC_OBJ_PU 

    Processing Unit, or (Logical) Processor. An execution unit (may share a core with some other logical processors, e.g. in the case of an SMT core).

    -

    This is the smallest object representing CPU resources, it cannot have any child except Misc objects.

    -

    Objects of this kind are always reported and can thus be used as fallback when others are not.

    -
    HWLOC_OBJ_L1CACHE 

    Level 1 Data (or Unified) Cache.

    -
    HWLOC_OBJ_L2CACHE 

    Level 2 Data (or Unified) Cache.

    -
    HWLOC_OBJ_L3CACHE 

    Level 3 Data (or Unified) Cache.

    -
    HWLOC_OBJ_L4CACHE 

    Level 4 Data (or Unified) Cache.

    -
    HWLOC_OBJ_L5CACHE 

    Level 5 Data (or Unified) Cache.

    -
    HWLOC_OBJ_L1ICACHE 

    Level 1 instruction Cache (filtered out by default).

    -
    HWLOC_OBJ_L2ICACHE 

    Level 2 instruction Cache (filtered out by default).

    -
    HWLOC_OBJ_L3ICACHE 

    Level 3 instruction Cache (filtered out by default).

    -
    HWLOC_OBJ_GROUP 

    Group objects. Objects which do not fit in the above but are detected by hwloc and are useful to take into account for affinity. For instance, some operating systems expose their arbitrary processors aggregation this way. And hwloc may insert such objects to group NUMA nodes according to their distances. See also What are these Group objects in my topology?.

    -

    These objects are removed when they do not bring any structure (see HWLOC_TYPE_FILTER_KEEP_STRUCTURE).

    -
    HWLOC_OBJ_NUMANODE 

    NUMA node. An object that contains memory that is directly and byte-accessible to the host processors. It is usually close to some cores (the corresponding objects are descendants of the NUMA node object in the hwloc tree).

    -

    This is the smallest object representing Memory resources, it cannot have any child except Misc objects. However it may have Memory-side cache parents.

    -

    There is always at least one such object in the topology even if the machine is not NUMA.

    -

    Memory objects are not listed in the main children list, but rather in the dedicated Memory children list.

    -

    NUMA nodes have a special depth HWLOC_TYPE_DEPTH_NUMANODE instead of a normal depth just like other objects in the main tree.

    -
    HWLOC_OBJ_BRIDGE 

    Bridge (filtered out by default). Any bridge (or PCI switch) that connects the host or an I/O bus, to another I/O bus.

    -

    Bridges are not added to the topology unless their filtering is changed (see hwloc_topology_set_type_filter() and hwloc_topology_set_io_types_filter()).

    -

    I/O objects are not listed in the main children list, but rather in the dedicated io children list. I/O objects have NULL CPU and node sets.

    -
    HWLOC_OBJ_PCI_DEVICE 

    PCI device (filtered out by default).

    -

    PCI devices are not added to the topology unless their filtering is changed (see hwloc_topology_set_type_filter() and hwloc_topology_set_io_types_filter()).

    -

    I/O objects are not listed in the main children list, but rather in the dedicated io children list. I/O objects have NULL CPU and node sets.

    -
    HWLOC_OBJ_OS_DEVICE 

    Operating system device (filtered out by default).

    -

    OS devices are not added to the topology unless their filtering is changed (see hwloc_topology_set_type_filter() and hwloc_topology_set_io_types_filter()).

    -

    I/O objects are not listed in the main children list, but rather in the dedicated io children list. I/O objects have NULL CPU and node sets.

    -
    HWLOC_OBJ_MISC 

    Miscellaneous objects (filtered out by default). Objects without particular meaning, that can e.g. be added by the application for its own use, or by hwloc for miscellaneous objects such as MemoryModule (DIMMs).

    -

    They are not added to the topology unless their filtering is changed (see hwloc_topology_set_type_filter()).

    -

    These objects are not listed in the main children list, but rather in the dedicated misc children list. Misc objects may only have Misc objects as children, and those are in the dedicated misc children list as well. Misc objects have NULL CPU and node sets.

    -
    HWLOC_OBJ_MEMCACHE 

    Memory-side cache (filtered out by default). A cache in front of a specific NUMA node.

    -

    This object always has at least one NUMA node as a memory child.

    -

    Memory objects are not listed in the main children list, but rather in the dedicated Memory children list.

    -

    Memory-side cache have a special depth HWLOC_TYPE_DEPTH_MEMCACHE instead of a normal depth just like other objects in the main tree.

    -
    HWLOC_OBJ_DIE 

    Die within a physical package. A subpart of the physical package, that contains multiple cores.

    -
    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_compare_types()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_compare_types (hwloc_obj_type_t type1,
    hwloc_obj_type_t type2 
    )
    -
    - -

    Compare the depth of two object types.

    -

    Types shouldn't be compared as they are, since newer ones may be added in the future.

    -
    Returns
    A negative integer if type1 objects usually include type2 objects.
    -
    -A positive integer if type1 objects are usually included in type2 objects.
    -
    -0 if type1 and type2 objects are the same.
    -
    -HWLOC_TYPE_UNORDERED if objects cannot be compared (because neither is usually contained in the other).
    -
    Note
    Object types containing CPUs can always be compared (usually, a machine contains packages, which contain caches, which contain cores, which contain PUs).
    -
    -HWLOC_OBJ_PU will always be the deepest, while HWLOC_OBJ_MACHINE is always the highest.
    -
    -This does not mean that the actual topology will respect that order: e.g. as of today cores may also contain caches, and packages may also contain nodes. This is thus just to be seen as a fallback comparison method.
    - -
    -
    -
    - - - - - - - -
    -
    -Data Structures | -Typedefs
    -
    Object Structure and Attributes
    -
    -
    - - - - - - - - -

    -Data Structures

    struct  hwloc_obj
     
    union  hwloc_obj_attr_u
     
    struct  hwloc_info_s
     
    - - - -

    -Typedefs

    typedef struct hwloc_obj * hwloc_obj_t
     
    -

    Detailed Description

    -

    Typedef Documentation

    - -

    ◆ hwloc_obj_t

    - -
    -
    - - - - -
    typedef struct hwloc_obj* hwloc_obj_t
    -
    - -

    Convenience typedef; a pointer to a struct hwloc_obj.

    - -
    -
    -
    - - - - - - - -
    -
    -Typedefs | -Functions
    -
    Topology Creation and Destruction
    -
    -
    - - - - -

    -Typedefs

    typedef struct hwloc_topology * hwloc_topology_t
     
    - - - - - - - - - - - - - -

    -Functions

    int hwloc_topology_init (hwloc_topology_t *topologyp)
     
    int hwloc_topology_load (hwloc_topology_t topology)
     
    void hwloc_topology_destroy (hwloc_topology_t topology)
     
    int hwloc_topology_dup (hwloc_topology_t *newtopology, hwloc_topology_t oldtopology)
     
    int hwloc_topology_abi_check (hwloc_topology_t topology)
     
    void hwloc_topology_check (hwloc_topology_t topology)
     
    -

    Detailed Description

    -

    Typedef Documentation

    - -

    ◆ hwloc_topology_t

    - -
    -
    - - - - -
    typedef struct hwloc_topology* hwloc_topology_t
    -
    - -

    Topology context.

    -

    To be initialized with hwloc_topology_init() and built with hwloc_topology_load().

    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_topology_abi_check()

    - -
    -
    - - - - - - - - -
    int hwloc_topology_abi_check (hwloc_topology_t topology)
    -
    - -

    Verify that the topology is compatible with the current hwloc library.

    -

    This is useful when using the same topology structure (in memory) in different libraries that may use different hwloc installations (for instance if one library embeds a specific version of hwloc, while another library uses a default system-wide hwloc installation).

    -

    If all libraries/programs use the same hwloc installation, this function always returns success.

    -
    Returns
    0 on success.
    -
    --1 with errno set to EINVAL if incompatible.
    -
    Note
    If sharing between processes with hwloc_shmem_topology_write(), the relevant check is already performed inside hwloc_shmem_topology_adopt().
    - -
    -
    - -

    ◆ hwloc_topology_check()

    - -
    -
    - - - - - - - - -
    void hwloc_topology_check (hwloc_topology_t topology)
    -
    - -

    Run internal checks on a topology structure.

    -

    The program aborts if an inconsistency is detected in the given topology.

    -
    Parameters
    - - -
    topologyis the topology to be checked
    -
    -
    -
    Note
    This routine is only useful to developers.
    -
    -The input topology should have been previously loaded with hwloc_topology_load().
    - -
    -
    - -

    ◆ hwloc_topology_destroy()

    - -
    -
    - - - - - - - - -
    void hwloc_topology_destroy (hwloc_topology_t topology)
    -
    - -

    Terminate and free a topology context.

    -
    Parameters
    - - -
    topologyis the topology to be freed
    -
    -
    - -
    -
    - -

    ◆ hwloc_topology_dup()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_dup (hwloc_topology_t * newtopology,
    hwloc_topology_t oldtopology 
    )
    -
    - -

    Duplicate a topology.

    -

    The entire topology structure as well as its objects are duplicated into a new one.

    -

    This is useful for keeping a backup while modifying a topology.

    -
    Returns
    0 on success, -1 on error.
    -
    Note
    Object userdata is not duplicated since hwloc does not know what it point to. The objects of both old and new topologies will point to the same userdata.
    - -
    -
    - -

    ◆ hwloc_topology_init()

    - -
    -
    - - - - - - - - -
    int hwloc_topology_init (hwloc_topology_t * topologyp)
    -
    - -

    Allocate a topology context.

    -
    Parameters
    - - -
    [out]topologypis assigned a pointer to the new allocated context.
    -
    -
    -
    Returns
    0 on success, -1 on error.
    - -
    -
    - -

    ◆ hwloc_topology_load()

    - -
    -
    - - - - - - - - -
    int hwloc_topology_load (hwloc_topology_t topology)
    -
    - -

    Build the actual topology.

    -

    Build the actual topology once initialized with hwloc_topology_init() and tuned with Topology Detection Configuration and Query and Changing the Source of Topology Discovery routines. No other routine may be called earlier using this topology context.

    -
    Parameters
    - - -
    topologyis the topology to be loaded with objects.
    -
    -
    -
    Returns
    0 on success, -1 on error.
    -
    Note
    On failure, the topology is reinitialized. It should be either destroyed with hwloc_topology_destroy() or configured and loaded again.
    -
    -This function may be called only once per topology.
    -
    -The binding of the current thread or process may temporarily change during this call but it will be restored before it returns.
    -
    See also
    Topology Detection Configuration and Query and Changing the Source of Topology Discovery
    - -
    -
    -
    - - - - - - - -
    -
    -Enumerations | -Functions
    -
    Object levels, depths and types
    -
    -
    - - - - -

    -Enumerations

    enum  hwloc_get_type_depth_e {
    -  HWLOC_TYPE_DEPTH_UNKNOWN -, HWLOC_TYPE_DEPTH_MULTIPLE -, HWLOC_TYPE_DEPTH_NUMANODE -, HWLOC_TYPE_DEPTH_BRIDGE -,
    -  HWLOC_TYPE_DEPTH_PCI_DEVICE -, HWLOC_TYPE_DEPTH_OS_DEVICE -, HWLOC_TYPE_DEPTH_MISC -, HWLOC_TYPE_DEPTH_MEMCACHE -
    - }
     
    - - - - - - - - - - - - - - - - - - - - - - - - - - - -

    -Functions

    int hwloc_topology_get_depth (hwloc_topology_t restrict topology)
     
    int hwloc_get_type_depth (hwloc_topology_t topology, hwloc_obj_type_t type)
     
    int hwloc_get_memory_parents_depth (hwloc_topology_t topology)
     
    static int hwloc_get_type_or_below_depth (hwloc_topology_t topology, hwloc_obj_type_t type)
     
    static int hwloc_get_type_or_above_depth (hwloc_topology_t topology, hwloc_obj_type_t type)
     
    hwloc_obj_type_t hwloc_get_depth_type (hwloc_topology_t topology, int depth)
     
    unsigned hwloc_get_nbobjs_by_depth (hwloc_topology_t topology, int depth)
     
    static int hwloc_get_nbobjs_by_type (hwloc_topology_t topology, hwloc_obj_type_t type)
     
    static hwloc_obj_t hwloc_get_root_obj (hwloc_topology_t topology)
     
    hwloc_obj_t hwloc_get_obj_by_depth (hwloc_topology_t topology, int depth, unsigned idx)
     
    static hwloc_obj_t hwloc_get_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx)
     
    static hwloc_obj_t hwloc_get_next_obj_by_depth (hwloc_topology_t topology, int depth, hwloc_obj_t prev)
     
    static hwloc_obj_t hwloc_get_next_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, hwloc_obj_t prev)
     
    -

    Detailed Description

    -

    Be sure to see the figure in Terms and Definitions that shows a complete topology tree, including depths, child/sibling/cousin relationships, and an example of an asymmetric topology where one package has fewer caches than its peers.

    -

    Enumeration Type Documentation

    - -

    ◆ hwloc_get_type_depth_e

    - -
    -
    - - - - -
    enum hwloc_get_type_depth_e
    -
    - - - - - - - - - -
    Enumerator
    HWLOC_TYPE_DEPTH_UNKNOWN 

    No object of given type exists in the topology.

    -
    HWLOC_TYPE_DEPTH_MULTIPLE 

    Objects of given type exist at different depth in the topology (only for Groups).

    -
    HWLOC_TYPE_DEPTH_NUMANODE 

    Virtual depth for NUMA nodes.

    -
    HWLOC_TYPE_DEPTH_BRIDGE 

    Virtual depth for bridge object level.

    -
    HWLOC_TYPE_DEPTH_PCI_DEVICE 

    Virtual depth for PCI device object level.

    -
    HWLOC_TYPE_DEPTH_OS_DEVICE 

    Virtual depth for software device object level.

    -
    HWLOC_TYPE_DEPTH_MISC 

    Virtual depth for Misc object.

    -
    HWLOC_TYPE_DEPTH_MEMCACHE 

    Virtual depth for MemCache object.

    -
    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_get_depth_type()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    hwloc_obj_type_t hwloc_get_depth_type (hwloc_topology_t topology,
    int depth 
    )
    -
    - -

    Returns the type of objects at depth depth.

    -

    depth should between 0 and hwloc_topology_get_depth()-1, or a virtual depth such as HWLOC_TYPE_DEPTH_NUMANODE.

    -
    Returns
    The type of objects at depth depth.
    -
    -(hwloc_obj_type_t)-1 if depth depth does not exist.
    - -
    -
    - -

    ◆ hwloc_get_memory_parents_depth()

    - -
    -
    - - - - - - - - -
    int hwloc_get_memory_parents_depth (hwloc_topology_t topology)
    -
    - -

    Return the depth of parents where memory objects are attached.

    -

    Memory objects have virtual negative depths because they are not part of the main CPU-side hierarchy of objects. This depth should not be compared with other level depths.

    -

    If all Memory objects are attached to Normal parents at the same depth, this parent depth may be compared to other as usual, for instance for knowing whether NUMA nodes is attached above or below Packages.

    -
    Returns
    The depth of Normal parents of all memory children if all these parents have the same depth. For instance the depth of the Package level if all NUMA nodes are attached to Package objects.
    -
    -HWLOC_TYPE_DEPTH_MULTIPLE if Normal parents of all memory children do not have the same depth. For instance if some NUMA nodes are attached to Packages while others are attached to Groups.
    - -
    -
    - -

    ◆ hwloc_get_nbobjs_by_depth()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    unsigned hwloc_get_nbobjs_by_depth (hwloc_topology_t topology,
    int depth 
    )
    -
    - -

    Returns the width of level at depth depth.

    -
    Returns
    The number of objects at topology depth depth.
    -
    -0 if there are no objects at depth depth.
    - -
    -
    - -

    ◆ hwloc_get_nbobjs_by_type()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static int hwloc_get_nbobjs_by_type (hwloc_topology_t topology,
    hwloc_obj_type_t type 
    )
    -     		-inlinestatic
    -
    - -

    Returns the width of level type type.

    -
    Returns
    The number of objects of type type.
    -
    --1 if there are multiple levels with objects of that type, e.g. HWLOC_OBJ_GROUP.
    -
    -0 if there are no objects at depth depth.
    - -
    -
    - -

    ◆ hwloc_get_next_obj_by_depth()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_next_obj_by_depth (hwloc_topology_t topology,
    int depth,
    hwloc_obj_t prev 
    )
    -     		-inlinestatic
    -
    - -

    Returns the next object at depth depth.

    -
    Returns
    The first object at depth depth if prev is NULL.
    -
    -The object after prev at depth depth if prev is not NULL.
    -
    -NULL if there is no such object.
    - -
    -
    - -

    ◆ hwloc_get_next_obj_by_type()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_next_obj_by_type (hwloc_topology_t topology,
    hwloc_obj_type_t type,
    hwloc_obj_t prev 
    )
    -     		-inlinestatic
    -
    - -

    Returns the next object of type type.

    -
    Returns
    The first object of type type if prev is NULL.
    -
    -The object after prev of type type if prev is not NULL.
    -
    -NULL if there is no such object.
    -
    -NULL if there are multiple levels with objects of that type (e.g. HWLOC_OBJ_GROUP), the caller may fallback to hwloc_get_obj_by_depth().
    - -
    -
    - -

    ◆ hwloc_get_obj_by_depth()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    hwloc_obj_t hwloc_get_obj_by_depth (hwloc_topology_t topology,
    int depth,
    unsigned idx 
    )
    -
    - -

    Returns the topology object at logical index idx from depth depth.

    -
    Returns
    The object if it exists.
    -
    -NULL if there is no object with this index and depth.
    - -
    -
    - -

    ◆ hwloc_get_obj_by_type()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_obj_by_type (hwloc_topology_t topology,
    hwloc_obj_type_t type,
    unsigned idx 
    )
    -     		-inlinestatic
    -
    - -

    Returns the topology object at logical index idx with type type.

    -
    Returns
    The object if it exists.
    -
    -NULL if there is no object with this index and type.
    -
    -NULL if there are multiple levels with objects of that type (e.g. HWLOC_OBJ_GROUP), the caller may fallback to hwloc_get_obj_by_depth().
    - -
    -
    - -

    ◆ hwloc_get_root_obj()

    - -
    -
    - - - - - -
    - - - - - - - - -
    static hwloc_obj_t hwloc_get_root_obj (hwloc_topology_t topology)
    -     		-inlinestatic
    -
    - -

    Returns the top-object of the topology-tree.

    -

    Its type is HWLOC_OBJ_MACHINE.

    -

    This function cannot return NULL.

    - -
    -
    - -

    ◆ hwloc_get_type_depth()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_get_type_depth (hwloc_topology_t topology,
    hwloc_obj_type_t type 
    )
    -
    - -

    Returns the depth of objects of type type.

    -
    Returns
    The depth of objects of type type.
    -
    -A negative virtual depth if a NUMA node, I/O or Misc object type is given. These objects are stored in special levels that are not CPU-related. This virtual depth may be passed to other hwloc functions such as hwloc_get_obj_by_depth() but it should not be considered as an actual depth by the application. In particular, it should not be compared with any other object depth or with the entire topology depth.
    -
    -HWLOC_TYPE_DEPTH_UNKNOWN if no object of this type is present on the underlying architecture, or if the OS doesn't provide this kind of information.
    -
    -HWLOC_TYPE_DEPTH_MULTIPLE if type HWLOC_OBJ_GROUP is given and multiple levels of Groups exist.
    -
    Note
    If the type is absent but a similar type is acceptable, see also hwloc_get_type_or_below_depth() and hwloc_get_type_or_above_depth().
    -
    See also
    hwloc_get_memory_parents_depth() for managing the depth of memory objects.
    -
    -hwloc_type_sscanf_as_depth() for returning the depth of objects whose type is given as a string.
    - -
    -
    - -

    ◆ hwloc_get_type_or_above_depth()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static int hwloc_get_type_or_above_depth (hwloc_topology_t topology,
    hwloc_obj_type_t type 
    )
    -     		-inlinestatic
    -
    - -

    Returns the depth of objects of type type or above.

    -

    If no object of this type is present on the underlying architecture, the function returns the depth of the first "present" object typically containing type.

    -

    This function is only meaningful for normal object types. If a memory, I/O or Misc object type is given, the corresponding virtual depth is always returned (see hwloc_get_type_depth()).

    -

    May return HWLOC_TYPE_DEPTH_MULTIPLE for HWLOC_OBJ_GROUP just like hwloc_get_type_depth().

    - -
    -
    - -

    ◆ hwloc_get_type_or_below_depth()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static int hwloc_get_type_or_below_depth (hwloc_topology_t topology,
    hwloc_obj_type_t type 
    )
    -     		-inlinestatic
    -
    - -

    Returns the depth of objects of type type or below.

    -

    If no object of this type is present on the underlying architecture, the function returns the depth of the first "present" object typically found inside type.

    -

    This function is only meaningful for normal object types. If a memory, I/O or Misc object type is given, the corresponding virtual depth is always returned (see hwloc_get_type_depth()).

    -

    May return HWLOC_TYPE_DEPTH_MULTIPLE for HWLOC_OBJ_GROUP just like hwloc_get_type_depth().

    - -
    -
    - -

    ◆ hwloc_topology_get_depth()

    - -
    -
    - - - - - - - - -
    int hwloc_topology_get_depth (hwloc_topology_t restrict topology)
    -
    - -

    Get the depth of the hierarchical tree of objects.

    -

    This is the depth of HWLOC_OBJ_PU objects plus one.

    -
    Returns
    the depth of the object tree.
    -
    Note
    NUMA nodes, I/O and Misc objects are ignored when computing the depth of the tree (they are placed on special levels).
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    Converting between Object Types and Attributes, and Strings
    -
    -
    - - - - - - - - - - - - -

    -Functions

    const char * hwloc_obj_type_string (hwloc_obj_type_t type)
     
    int hwloc_obj_type_snprintf (char *restrict string, size_t size, hwloc_obj_t obj, int verbose)
     
    int hwloc_obj_attr_snprintf (char *restrict string, size_t size, hwloc_obj_t obj, const char *restrict separator, int verbose)
     
    int hwloc_type_sscanf (const char *string, hwloc_obj_type_t *typep, union hwloc_obj_attr_u *attrp, size_t attrsize)
     
    int hwloc_type_sscanf_as_depth (const char *string, hwloc_obj_type_t *typep, hwloc_topology_t topology, int *depthp)
     
    -

    Detailed Description

    -

    Function Documentation

    - -

    ◆ hwloc_obj_attr_snprintf()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_obj_attr_snprintf (char *restrict string,
    size_t size,
    hwloc_obj_t obj,
    const char *restrict separator,
    int verbose 
    )
    -
    - -

    Stringify the attributes of a given topology object into a human-readable form.

    -

    Attribute values are separated by separator.

    -

    Only the major attributes are printed in non-verbose mode.

    -

    If size is 0, string may safely be NULL.

    -
    Returns
    the number of characters that were actually written if not truncating, or that would have been written (not including the ending \0).
    - -
    -
    - -

    ◆ hwloc_obj_type_snprintf()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_obj_type_snprintf (char *restrict string,
    size_t size,
    hwloc_obj_t obj,
    int verbose 
    )
    -
    - -

    Stringify the type of a given topology object into a human-readable form.

    -

    Contrary to hwloc_obj_type_string(), this function includes object-specific attributes (such as the Group depth, the Bridge type, or OS device type) in the output, and it requires the caller to provide the output buffer.

    -

    The output is guaranteed to be the same for all objects of a same topology level.

    -

    If verbose is 1, longer type names are used, e.g. L1Cache instead of L1.

    -

    The output string may be parsed back by hwloc_type_sscanf().

    -

    If size is 0, string may safely be NULL.

    -
    Returns
    the number of characters that were actually written if not truncating, or that would have been written (not including the ending \0).
    - -
    -
    - -

    ◆ hwloc_obj_type_string()

    - -
    -
    - - - - - - - - -
    const char * hwloc_obj_type_string (hwloc_obj_type_t type)
    -
    - -

    Return a constant stringified object type.

    -

    This function is the basic way to convert a generic type into a string. The output string may be parsed back by hwloc_type_sscanf().

    -

    hwloc_obj_type_snprintf() may return a more precise output for a specific object, but it requires the caller to provide the output buffer.

    -
    Returns
    A constant string containing the object type name or "Unknown".
    - -
    -
    - -

    ◆ hwloc_type_sscanf()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_type_sscanf (const char * string,
    hwloc_obj_type_t * typep,
    union hwloc_obj_attr_u * attrp,
    size_t attrsize 
    )
    -
    - -

    Return an object type and attributes from a type string.

    -

    Convert strings such as "Package" or "L1iCache" into the corresponding types. Matching is case-insensitive, and only the first letters are actually required to match.

    -

    The matched object type is set in typep (which cannot be NULL).

    -

    Type-specific attributes, for instance Cache type, Cache depth, Group depth, Bridge type or OS Device type may be returned in attrp. Attributes that are not specified in the string (for instance "Group" without a depth, or "L2Cache" without a cache type) are set to -1.

    -

    attrp is only filled if not NULL and if its size specified in attrsize is large enough. It should be at least as large as union hwloc_obj_attr_u.

    -
    Returns
    0 if a type was correctly identified, otherwise -1.
    -
    Note
    This function is guaranteed to match any string returned by hwloc_obj_type_string() or hwloc_obj_type_snprintf().
    -
    -This is an extended version of the now deprecated hwloc_obj_type_sscanf().
    - -
    -
    - -

    ◆ hwloc_type_sscanf_as_depth()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_type_sscanf_as_depth (const char * string,
    hwloc_obj_type_t * typep,
    hwloc_topology_t topology,
    int * depthp 
    )
    -
    - -

    Return an object type and its level depth from a type string.

    -

    Convert strings such as "Package" or "L1iCache" into the corresponding types and return in depthp the depth of the corresponding level in the topology topology.

    -

    If no object of this type is present on the underlying architecture, HWLOC_TYPE_DEPTH_UNKNOWN is returned.

    -

    If multiple such levels exist (for instance if giving Group without any depth), the function may return HWLOC_TYPE_DEPTH_MULTIPLE instead.

    -

    The matched object type is set in typep if typep is non NULL.

    -
    Note
    This function is similar to hwloc_type_sscanf() followed by hwloc_get_type_depth() but it also automatically disambiguates multiple group levels etc.
    -
    -This function is guaranteed to match any string returned by hwloc_obj_type_string() or hwloc_obj_type_snprintf().
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    Consulting and Adding Key-Value Info Attributes
    -
    -
    - - - - - - -

    -Functions

    static const char * hwloc_obj_get_info_by_name (hwloc_obj_t obj, const char *name)
     
    int hwloc_obj_add_info (hwloc_obj_t obj, const char *name, const char *value)
     
    -

    Detailed Description

    -

    Function Documentation

    - -

    ◆ hwloc_obj_add_info()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_obj_add_info (hwloc_obj_t obj,
    const char * name,
    const char * value 
    )
    -
    - -

    Add the given info name and value pair to the given object.

    -

    The info is appended to the existing info array even if another key with the same name already exists.

    -

    The input strings are copied before being added in the object infos.

    -
    Returns
    0 on success, -1 on error.
    -
    Note
    This function may be used to enforce object colors in the lstopo graphical output by using "lstopoStyle" as a name and "Background=#rrggbb" as a value. See CUSTOM COLORS in the lstopo(1) manpage for details.
    -
    -If value contains some non-printable characters, they will be dropped when exporting to XML, see hwloc_topology_export_xml() in hwloc/export.h.
    - -
    -
    - -

    ◆ hwloc_obj_get_info_by_name()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static const char * hwloc_obj_get_info_by_name (hwloc_obj_t obj,
    const char * name 
    )
    -     		-inlinestatic
    -
    - -

    Search the given key name in object infos and return the corresponding value.

    -

    If multiple keys match the given name, only the first one is returned.

    -
    Returns
    A pointer to the value string if it exists.
    -
    -NULL if no such key exists.
    -
    Note
    The string should not be freed by the caller, it belongs to the hwloc library.
    - -
    -
    -
    - - - - - - - -
    -
    -Enumerations | -Functions
    -
    CPU binding
    -
    -
    - - - - -

    -Enumerations

    enum  hwloc_cpubind_flags_t { HWLOC_CPUBIND_PROCESS -, HWLOC_CPUBIND_THREAD -, HWLOC_CPUBIND_STRICT -, HWLOC_CPUBIND_NOMEMBIND - }
     
    - - - - - - - - - - - - - - - - - -

    -Functions

    int hwloc_set_cpubind (hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags)
     
    int hwloc_get_cpubind (hwloc_topology_t topology, hwloc_cpuset_t set, int flags)
     
    int hwloc_set_proc_cpubind (hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_cpuset_t set, int flags)
     
    int hwloc_get_proc_cpubind (hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags)
     
    int hwloc_set_thread_cpubind (hwloc_topology_t topology, hwloc_thread_t thread, hwloc_const_cpuset_t set, int flags)
     
    int hwloc_get_thread_cpubind (hwloc_topology_t topology, hwloc_thread_t thread, hwloc_cpuset_t set, int flags)
     
    int hwloc_get_last_cpu_location (hwloc_topology_t topology, hwloc_cpuset_t set, int flags)
     
    int hwloc_get_proc_last_cpu_location (hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags)
     
    -

    Detailed Description

    -

    Some operating systems only support binding threads or processes to a single PU. Others allow binding to larger sets such as entire Cores or Packages or even random sets of individual PUs. In such operating system, the scheduler is free to run the task on one of these PU, then migrate it to another PU, etc. It is often useful to call hwloc_bitmap_singlify() on the target CPU set before passing it to the binding function to avoid these expensive migrations. See the documentation of hwloc_bitmap_singlify() for details.

    -

    Some operating systems do not provide all hwloc-supported mechanisms to bind processes, threads, etc. hwloc_topology_get_support() may be used to query about the actual CPU binding support in the currently used operating system.

    -

    When the requested binding operation is not available and the HWLOC_CPUBIND_STRICT flag was passed, the function returns -1. errno is set to ENOSYS when it is not possible to bind the requested kind of object processes/threads. errno is set to EXDEV when the requested cpuset can not be enforced (e.g. some systems only allow one CPU, and some other systems only allow one NUMA node).

    -

    If HWLOC_CPUBIND_STRICT was not passed, the function may fail as well, or the operating system may use a slightly different operation (with side-effects, smaller binding set, etc.) when the requested operation is not exactly supported.

    -

    The most portable version that should be preferred over the others, whenever possible, is the following one which just binds the current program, assuming it is single-threaded:

    -
    hwloc_set_cpubind(topology, set, 0),
    -
    hwloc_set_cpubind
    int hwloc_set_cpubind(hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags)
    Bind current process or thread on CPUs given in physical bitmap set.
    -

    If the program may be multithreaded, the following one should be preferred to only bind the current thread:

    -
    hwloc_set_cpubind(topology, set, HWLOC_CPUBIND_THREAD),
    -
    HWLOC_CPUBIND_THREAD
    @ HWLOC_CPUBIND_THREAD
    Bind current thread of current process.
    Definition: hwloc.h:1214
    -
    See also
    Some example codes are available under doc/examples/ in the source tree.
    -
    Note
    To unbind, just call the binding function with either a full cpuset or a cpuset equal to the system cpuset.
    -
    -On some operating systems, CPU binding may have effects on memory binding, see HWLOC_CPUBIND_NOMEMBIND
    -
    -Running lstopo --top or hwloc-ps can be a very convenient tool to check how binding actually happened.
    -

    Enumeration Type Documentation

    - -

    ◆ hwloc_cpubind_flags_t

    - -
    -
    - - - - -
    enum hwloc_cpubind_flags_t
    -
    - -

    Process/Thread binding flags.

    -

    These bit flags can be used to refine the binding policy.

    -

    The default (0) is to bind the current process, assumed to be single-threaded, in a non-strict way. This is the most portable way to bind as all operating systems usually provide it.

    -
    Note
    Not all systems support all kinds of binding. See the "Detailed Description" section of CPU binding for a description of errors that can occur.
    - - - - - -
    Enumerator
    HWLOC_CPUBIND_PROCESS 

    Bind all threads of the current (possibly) multithreaded process.

    -
    HWLOC_CPUBIND_THREAD 

    Bind current thread of current process.

    -
    HWLOC_CPUBIND_STRICT 

    Request for strict binding from the OS.

    -

    By default, when the designated CPUs are all busy while other CPUs are idle, operating systems may execute the thread/process on those other CPUs instead of the designated CPUs, to let them progress anyway. Strict binding means that the thread/process will _never_ execute on other CPUs than the designated CPUs, even when those are busy with other tasks and other CPUs are idle.

    -
    Note
    Depending on the operating system, strict binding may not be possible (e.g., the OS does not implement it) or not allowed (e.g., for an administrative reasons), and the function will fail in that case.
    -

    When retrieving the binding of a process, this flag checks whether all its threads actually have the same binding. If the flag is not given, the binding of each thread will be accumulated.

    -
    Note
    This flag is meaningless when retrieving the binding of a thread.
    -
    HWLOC_CPUBIND_NOMEMBIND 

    Avoid any effect on memory binding.

    -

    On some operating systems, some CPU binding function would also bind the memory on the corresponding NUMA node. It is often not a problem for the application, but if it is, setting this flag will make hwloc avoid using OS functions that would also bind memory. This will however reduce the support of CPU bindings, i.e. potentially return -1 with errno set to ENOSYS in some cases.

    -

    This flag is only meaningful when used with functions that set the CPU binding. It is ignored when used with functions that get CPU binding information.

    -
    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_get_cpubind()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_get_cpubind (hwloc_topology_t topology,
    hwloc_cpuset_t set,
    int flags 
    )
    -
    - -

    Get current process or thread binding.

    -

    The CPU-set set (previously allocated by the caller) is filled with the list of PUs which the process or thread (according to flags) was last bound to.

    -
    Returns
    0 on success, -1 on error.
    - -
    -
    - -

    ◆ hwloc_get_last_cpu_location()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_get_last_cpu_location (hwloc_topology_t topology,
    hwloc_cpuset_t set,
    int flags 
    )
    -
    - -

    Get the last physical CPU where the current process or thread ran.

    -

    The CPU-set set (previously allocated by the caller) is filled with the list of PUs which the process or thread (according to flags) last ran on.

    -

    The operating system may move some tasks from one processor to another at any time according to their binding, so this function may return something that is already outdated.

    -

    flags can include either HWLOC_CPUBIND_PROCESS or HWLOC_CPUBIND_THREAD to specify whether the query should be for the whole process (union of all CPUs on which all threads are running), or only the current thread. If the process is single-threaded, flags can be set to zero to let hwloc use whichever method is available on the underlying OS.

    -
    Returns
    0 on success, -1 on error.
    - -
    -
    - -

    ◆ hwloc_get_proc_cpubind()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_get_proc_cpubind (hwloc_topology_t topology,
    hwloc_pid_t pid,
    hwloc_cpuset_t set,
    int flags 
    )
    -
    - -

    Get the current physical binding of process pid.

    -

    The CPU-set set (previously allocated by the caller) is filled with the list of PUs which the process was last bound to.

    -
    Returns
    0 on success, -1 on error.
    -
    Note
    hwloc_pid_t is pid_t on Unix platforms, and HANDLE on native Windows platforms.
    -
    -As a special case on Linux, if a tid (thread ID) is supplied instead of a pid (process ID) and HWLOC_CPUBIND_THREAD is passed in flags, the binding for that specific thread is returned.
    -
    -On non-Linux systems, HWLOC_CPUBIND_THREAD can not be used in flags.
    - -
    -
    - -

    ◆ hwloc_get_proc_last_cpu_location()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_get_proc_last_cpu_location (hwloc_topology_t topology,
    hwloc_pid_t pid,
    hwloc_cpuset_t set,
    int flags 
    )
    -
    - -

    Get the last physical CPU where a process ran.

    -

    The CPU-set set (previously allocated by the caller) is filled with the list of PUs which the process last ran on.

    -

    The operating system may move some tasks from one processor to another at any time according to their binding, so this function may return something that is already outdated.

    -
    Returns
    0 on success, -1 on error.
    -
    Note
    hwloc_pid_t is pid_t on Unix platforms, and HANDLE on native Windows platforms.
    -
    -As a special case on Linux, if a tid (thread ID) is supplied instead of a pid (process ID) and HWLOC_CPUBIND_THREAD is passed in flags, the last CPU location of that specific thread is returned.
    -
    -On non-Linux systems, HWLOC_CPUBIND_THREAD can not be used in flags.
    - -
    -
    - -

    ◆ hwloc_get_thread_cpubind()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_get_thread_cpubind (hwloc_topology_t topology,
    hwloc_thread_t thread,
    hwloc_cpuset_t set,
    int flags 
    )
    -
    - -

    Get the current physical binding of thread tid.

    -

    The CPU-set set (previously allocated by the caller) is filled with the list of PUs which the thread was last bound to.

    -
    Returns
    0 on success, -1 on error.
    -
    Note
    hwloc_thread_t is pthread_t on Unix platforms, and HANDLE on native Windows platforms.
    -
    -HWLOC_CPUBIND_PROCESS can not be used in flags.
    - -
    -
    - -

    ◆ hwloc_set_cpubind()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_set_cpubind (hwloc_topology_t topology,
    hwloc_const_cpuset_t set,
    int flags 
    )
    -
    - -

    Bind current process or thread on CPUs given in physical bitmap set.

    -
    Returns
    0 on success.
    -
    --1 with errno set to ENOSYS if the action is not supported.
    -
    --1 with errno set to EXDEV if the binding cannot be enforced.
    - -
    -
    - -

    ◆ hwloc_set_proc_cpubind()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_set_proc_cpubind (hwloc_topology_t topology,
    hwloc_pid_t pid,
    hwloc_const_cpuset_t set,
    int flags 
    )
    -
    - -

    Bind a process pid on CPUs given in physical bitmap set.

    -
    Returns
    0 on success, -1 on error.
    -
    Note
    hwloc_pid_t is pid_t on Unix platforms, and HANDLE on native Windows platforms.
    -
    -As a special case on Linux, if a tid (thread ID) is supplied instead of a pid (process ID) and HWLOC_CPUBIND_THREAD is passed in flags, the binding is applied to that specific thread.
    -
    -On non-Linux systems, HWLOC_CPUBIND_THREAD can not be used in flags.
    - -
    -
    - -

    ◆ hwloc_set_thread_cpubind()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_set_thread_cpubind (hwloc_topology_t topology,
    hwloc_thread_t thread,
    hwloc_const_cpuset_t set,
    int flags 
    )
    -
    - -

    Bind a thread thread on CPUs given in physical bitmap set.

    -
    Returns
    0 on success, -1 on error.
    -
    Note
    hwloc_thread_t is pthread_t on Unix platforms, and HANDLE on native Windows platforms.
    -
    -HWLOC_CPUBIND_PROCESS can not be used in flags.
    - -
    -
    -
    - - - - - - - -
    -
    -Enumerations | -Functions
    -
    Memory binding
    -
    -
    - - - - - - -

    -Enumerations

    enum  hwloc_membind_policy_t {
    -  HWLOC_MEMBIND_DEFAULT -, HWLOC_MEMBIND_FIRSTTOUCH -, HWLOC_MEMBIND_BIND -, HWLOC_MEMBIND_INTERLEAVE -,
    -  HWLOC_MEMBIND_NEXTTOUCH -, HWLOC_MEMBIND_MIXED -
    - }
     
    enum  hwloc_membind_flags_t {
    -  HWLOC_MEMBIND_PROCESS -, HWLOC_MEMBIND_THREAD -, HWLOC_MEMBIND_STRICT -, HWLOC_MEMBIND_MIGRATE -,
    -  HWLOC_MEMBIND_NOCPUBIND -, HWLOC_MEMBIND_BYNODESET -
    - }
     
    - - - - - - - - - - - - - - - - - - - - - - - -

    -Functions

    int hwloc_set_membind (hwloc_topology_t topology, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags)
     
    int hwloc_get_membind (hwloc_topology_t topology, hwloc_bitmap_t set, hwloc_membind_policy_t *policy, int flags)
     
    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)
     
    int hwloc_get_proc_membind (hwloc_topology_t topology, hwloc_pid_t pid, hwloc_bitmap_t set, hwloc_membind_policy_t *policy, int flags)
     
    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)
     
    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)
     
    int hwloc_get_area_memlocation (hwloc_topology_t topology, const void *addr, size_t len, hwloc_bitmap_t set, int flags)
     
    void * hwloc_alloc (hwloc_topology_t topology, size_t len)
     
    void * hwloc_alloc_membind (hwloc_topology_t topology, size_t len, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags)
     
    static void * hwloc_alloc_membind_policy (hwloc_topology_t topology, size_t len, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags)
     
    int hwloc_free (hwloc_topology_t topology, void *addr, size_t len)
     
    -

    Detailed Description

    -

    Memory binding can be done three ways:

    -
      -
    • explicit memory allocation thanks to hwloc_alloc_membind() and friends: the binding will have effect on the memory allocated by these functions.
      • -
    • implicit memory binding through binding policy: hwloc_set_membind() and friends only define the current policy of the process, which will be applied to the subsequent calls to malloc() and friends.
      • -
    • migration of existing memory ranges, thanks to hwloc_set_area_membind() and friends, which move already-allocated data.
      • -
    -

    Not all operating systems support all three ways. hwloc_topology_get_support() may be used to query about the actual memory binding support in the currently used operating system.

    -

    When the requested binding operation is not available and the HWLOC_MEMBIND_STRICT flag was passed, the function returns -1. errno will be set to ENOSYS when the system does support the specified action or policy (e.g., some systems only allow binding memory on a per-thread basis, whereas other systems only allow binding memory for all threads in a process). errno will be set to EXDEV when the requested set can not be enforced (e.g., some systems only allow binding memory to a single NUMA node).

    -

    If HWLOC_MEMBIND_STRICT was not passed, the function may fail as well, or the operating system may use a slightly different operation (with side-effects, smaller binding set, etc.) when the requested operation is not exactly supported.

    -

    The most portable form that should be preferred over the others whenever possible is as follows. It allocates some memory hopefully bound to the specified set. To do so, hwloc will possibly have to change the current memory binding policy in order to actually get the memory bound, if the OS does not provide any other way to simply allocate bound memory without changing the policy for all allocations. That is the difference with hwloc_alloc_membind(), which will never change the current memory binding policy.

    -
    hwloc_alloc_membind_policy(topology, size, set,
    -
    HWLOC_MEMBIND_BIND, 0);
    -
    hwloc_alloc_membind_policy
    static void * hwloc_alloc_membind_policy(hwloc_topology_t topology, size_t len, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags)
    Allocate some memory on NUMA memory nodes specified by set.
    -
    HWLOC_MEMBIND_BIND
    @ HWLOC_MEMBIND_BIND
    Allocate memory on the specified nodes.
    Definition: hwloc.h:1488
    -

    Each hwloc memory binding function takes a bitmap argument that is a CPU set by default, or a NUMA memory node set if the flag HWLOC_MEMBIND_BYNODESET is specified. See Object Sets (hwloc_cpuset_t and hwloc_nodeset_t) and The bitmap API for a discussion of CPU sets and NUMA memory node sets. It is also possible to convert between CPU set and node set using hwloc_cpuset_to_nodeset() or hwloc_cpuset_from_nodeset().

    -

    Memory binding by CPU set cannot work for CPU-less NUMA memory nodes. Binding by nodeset should therefore be preferred whenever possible.

    -
    See also
    Some example codes are available under doc/examples/ in the source tree.
    -
    Note
    On some operating systems, memory binding affects the CPU binding; see HWLOC_MEMBIND_NOCPUBIND
    -

    Enumeration Type Documentation

    - -

    ◆ hwloc_membind_flags_t

    - -
    -
    - - - - -
    enum hwloc_membind_flags_t
    -
    - -

    Memory binding flags.

    -

    These flags can be used to refine the binding policy. All flags can be logically OR'ed together with the exception of HWLOC_MEMBIND_PROCESS and HWLOC_MEMBIND_THREAD; these two flags are mutually exclusive.

    -

    Not all systems support all kinds of binding. hwloc_topology_get_support() may be used to query about the actual memory binding support in the currently used operating system. See the "Detailed Description" section of Memory binding for a description of errors that can occur.

    - - - - - - - -
    Enumerator
    HWLOC_MEMBIND_PROCESS 

    Set policy for all threads of the specified (possibly multithreaded) process. This flag is mutually exclusive with HWLOC_MEMBIND_THREAD.

    -
    HWLOC_MEMBIND_THREAD 

    Set policy for a specific thread of the current process. This flag is mutually exclusive with HWLOC_MEMBIND_PROCESS.

    -
    HWLOC_MEMBIND_STRICT 

    Request strict binding from the OS. The function will fail if the binding can not be guaranteed / completely enforced.

    -

    This flag has slightly different meanings depending on which function it is used with.

    -
    HWLOC_MEMBIND_MIGRATE 

    Migrate existing allocated memory. If the memory cannot be migrated and the HWLOC_MEMBIND_STRICT flag is passed, an error will be returned.

    -
    HWLOC_MEMBIND_NOCPUBIND 

    Avoid any effect on CPU binding.

    -

    On some operating systems, some underlying memory binding functions also bind the application to the corresponding CPU(s). Using this flag will cause hwloc to avoid using OS functions that could potentially affect CPU bindings. Note, however, that using NOCPUBIND may reduce hwloc's overall memory binding support. Specifically: some of hwloc's memory binding functions may fail with errno set to ENOSYS when used with NOCPUBIND.

    -
    HWLOC_MEMBIND_BYNODESET 

    Consider the bitmap argument as a nodeset.

    -

    The bitmap argument is considered a nodeset if this flag is given, or a cpuset otherwise by default.

    -

    Memory binding by CPU set cannot work for CPU-less NUMA memory nodes. Binding by nodeset should therefore be preferred whenever possible.

    -
    - -
    -
    - -

    ◆ hwloc_membind_policy_t

    - -
    -
    - - - - -
    enum hwloc_membind_policy_t
    -
    - -

    Memory binding policy.

    -

    These constants can be used to choose the binding policy. Only one policy can be used at a time (i.e., the values cannot be OR'ed together).

    -

    Not all systems support all kinds of binding. hwloc_topology_get_support() may be used to query about the actual memory binding policy support in the currently used operating system. See the "Detailed Description" section of Memory binding for a description of errors that can occur.

    - - - - - - - -
    Enumerator
    HWLOC_MEMBIND_DEFAULT 

    Reset the memory allocation policy to the system default. Depending on the operating system, this may correspond to HWLOC_MEMBIND_FIRSTTOUCH (Linux, FreeBSD), or HWLOC_MEMBIND_BIND (AIX, HP-UX, Solaris, Windows). This policy is never returned by get membind functions. The nodeset argument is ignored.

    -
    HWLOC_MEMBIND_FIRSTTOUCH 

    Allocate each memory page individually on the local NUMA node of the thread that touches it.

    -

    The given nodeset should usually be hwloc_topology_get_topology_nodeset() so that the touching thread may run and allocate on any node in the system.

    -

    On AIX, if the nodeset is smaller, pages are allocated locally (if the local node is in the nodeset) or from a random non-local node (otherwise).

    -
    HWLOC_MEMBIND_BIND 

    Allocate memory on the specified nodes.

    -
    HWLOC_MEMBIND_INTERLEAVE 

    Allocate memory on the given nodes in an interleaved / round-robin manner. The precise layout of the memory across multiple NUMA nodes is OS/system specific. Interleaving can be useful when threads distributed across the specified NUMA nodes will all be accessing the whole memory range concurrently, since the interleave will then balance the memory references.

    -
    HWLOC_MEMBIND_NEXTTOUCH 

    For each page bound with this policy, by next time it is touched (and next time only), it is moved from its current location to the local NUMA node of the thread where the memory reference occurred (if it needs to be moved at all).

    -
    HWLOC_MEMBIND_MIXED 

    Returned by get_membind() functions when multiple threads or parts of a memory area have differing memory binding policies. Also returned when binding is unknown because binding hooks are empty when the topology is loaded from XML without HWLOC_THISSYSTEM=1, etc.

    -
    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_alloc()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    void * hwloc_alloc (hwloc_topology_t topology,
    size_t len 
    )
    -
    - -

    Allocate some memory.

    -

    This is equivalent to malloc(), except that it tries to allocate page-aligned memory from the OS.

    -
    Returns
    a pointer to the allocated area, or NULL on error.
    -
    Note
    The allocated memory should be freed with hwloc_free().
    - -
    -
    - -

    ◆ hwloc_alloc_membind()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    void * hwloc_alloc_membind (hwloc_topology_t topology,
    size_t len,
    hwloc_const_bitmap_t set,
    hwloc_membind_policy_t policy,
    int flags 
    )
    -
    - -

    Allocate some memory on NUMA memory nodes specified by set.

    -
    Returns
    a pointer to the allocated area.
    -
    -NULL with errno set to ENOSYS if the action is not supported and HWLOC_MEMBIND_STRICT is given.
    -
    -NULL with errno set to EXDEV if the binding cannot be enforced and HWLOC_MEMBIND_STRICT is given.
    -
    -NULL with errno set to ENOMEM if the memory allocation failed even before trying to bind.
    -

    If HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset. Otherwise it's a cpuset.

    -
    Note
    The allocated memory should be freed with hwloc_free().
    - -
    -
    - -

    ◆ hwloc_alloc_membind_policy()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static void * hwloc_alloc_membind_policy (hwloc_topology_t topology,
    size_t len,
    hwloc_const_bitmap_t set,
    hwloc_membind_policy_t policy,
    int flags 
    )
    -     		-inlinestatic
    -
    - -

    Allocate some memory on NUMA memory nodes specified by set.

    -

    First, try to allocate properly with hwloc_alloc_membind(). On failure, the current process or thread memory binding policy is changed with hwloc_set_membind() before allocating memory. Thus this function works in more cases, at the expense of changing the current state (possibly affecting future allocations that would not specify any policy).

    -

    If HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset. Otherwise it's a cpuset.

    -
    Returns
    a pointer to the allocated area, or NULL on error.
    - -
    -
    - -

    ◆ hwloc_free()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_free (hwloc_topology_t topology,
    void * addr,
    size_t len 
    )
    -
    - -

    Free memory that was previously allocated by hwloc_alloc() or hwloc_alloc_membind().

    -
    Returns
    0 on success, -1 on error.
    - -
    -
    - -

    ◆ hwloc_get_area_membind()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    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 
    )
    -
    - -

    Query the CPUs near the physical NUMA node(s) and binding policy of the memory identified by (addr, len ).

    -

    The bitmap set (previously allocated by the caller) is filled with the memory area binding.

    -

    This function has two output parameters: set and policy. The values returned in these parameters depend on both the flags passed in and the memory binding policies and nodesets of the pages in the address range.

    -

    If HWLOC_MEMBIND_STRICT is specified, the target pages are first checked to see if they all have the same memory binding policy and nodeset. If they do not, -1 is returned and errno is set to EXDEV. If they are identical across all pages, the set and policy are returned in set and policy, respectively.

    -

    If HWLOC_MEMBIND_STRICT is not specified, the union of all NUMA node(s) containing pages in the address range is calculated. If all pages in the target have the same policy, it is returned in policy. Otherwise, policy is set to HWLOC_MEMBIND_MIXED.

    -

    If HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset. Otherwise it's a cpuset.

    -

    If any other flags are specified, -1 is returned and errno is set to EINVAL.

    -
    Returns
    0 on success.
    -
    --1 with errno set to EINVAL if len is 0.
    - -
    -
    - -

    ◆ hwloc_get_area_memlocation()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_get_area_memlocation (hwloc_topology_t topology,
    const void * addr,
    size_t len,
    hwloc_bitmap_t set,
    int flags 
    )
    -
    - -

    Get the NUMA nodes where memory identified by (addr, len ) is physically allocated.

    -

    The bitmap set (previously allocated by the caller) is filled according to the NUMA nodes where the memory area pages are physically allocated. If no page is actually allocated yet, set may be empty.

    -

    If pages spread to multiple nodes, it is not specified whether they spread equitably, or whether most of them are on a single node, etc.

    -

    The operating system may move memory pages from one processor to another at any time according to their binding, so this function may return something that is already outdated.

    -

    If HWLOC_MEMBIND_BYNODESET is specified in flags, set is considered a nodeset. Otherwise it's a cpuset.

    -

    If len is 0, set is emptied.

    -
    Returns
    0 on success, -1 on error.
    - -
    -
    - -

    ◆ hwloc_get_membind()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_get_membind (hwloc_topology_t topology,
    hwloc_bitmap_t set,
    hwloc_membind_policy_t * policy,
    int flags 
    )
    -
    - -

    Query the default memory binding policy and physical locality of the current process or thread.

    -

    The bitmap set (previously allocated by the caller) is filled with the process or thread memory binding.

    -

    This function has two output parameters: set and policy. The values returned in these parameters depend on both the flags passed in and the current memory binding policies and nodesets in the queried target.

    -

    Passing the HWLOC_MEMBIND_PROCESS flag specifies that the query target is the current policies and nodesets for all the threads in the current process. Passing HWLOC_MEMBIND_THREAD specifies that the query target is the current policy and nodeset for only the thread invoking this function.

    -

    If neither of these flags are passed (which is the most portable method), the process is assumed to be single threaded. This allows hwloc to use either process-based OS functions or thread-based OS functions, depending on which are available.

    -

    HWLOC_MEMBIND_STRICT is only meaningful when HWLOC_MEMBIND_PROCESS is also specified. In this case, hwloc will check the default memory policies and nodesets for all threads in the process. If they are not identical, -1 is returned and errno is set to EXDEV. If they are identical, the values are returned in set and policy.

    -

    Otherwise, if HWLOC_MEMBIND_PROCESS is specified (and HWLOC_MEMBIND_STRICT is not specified), the default set from each thread is logically OR'ed together. If all threads' default policies are the same, policy is set to that policy. If they are different, policy is set to HWLOC_MEMBIND_MIXED.

    -

    In the HWLOC_MEMBIND_THREAD case (or when neither HWLOC_MEMBIND_PROCESS or HWLOC_MEMBIND_THREAD is specified), there is only one set and policy; they are returned in set and policy, respectively.

    -

    If HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset. Otherwise it's a cpuset.

    -

    If any other flags are specified, -1 is returned and errno is set to EINVAL.

    -
    Returns
    0 on success, -1 on error.
    - -
    -
    - -

    ◆ hwloc_get_proc_membind()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_get_proc_membind (hwloc_topology_t topology,
    hwloc_pid_t pid,
    hwloc_bitmap_t set,
    hwloc_membind_policy_t * policy,
    int flags 
    )
    -
    - -

    Query the default memory binding policy and physical locality of the specified process.

    -

    The bitmap set (previously allocated by the caller) is filled with the process memory binding.

    -

    This function has two output parameters: set and policy. The values returned in these parameters depend on both the flags passed in and the current memory binding policies and nodesets in the queried target.

    -

    Passing the HWLOC_MEMBIND_PROCESS flag specifies that the query target is the current policies and nodesets for all the threads in the specified process. If HWLOC_MEMBIND_PROCESS is not specified (which is the most portable method), the process is assumed to be single threaded. This allows hwloc to use either process-based OS functions or thread-based OS functions, depending on which are available.

    -

    Note that it does not make sense to pass HWLOC_MEMBIND_THREAD to this function.

    -

    If HWLOC_MEMBIND_STRICT is specified, hwloc will check the default memory policies and nodesets for all threads in the specified process. If they are not identical, -1 is returned and errno is set to EXDEV. If they are identical, the values are returned in set and policy.

    -

    Otherwise, set is set to the logical OR of all threads' default set. If all threads' default policies are the same, policy is set to that policy. If they are different, policy is set to HWLOC_MEMBIND_MIXED.

    -

    If HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset. Otherwise it's a cpuset.

    -

    If any other flags are specified, -1 is returned and errno is set to EINVAL.

    -
    Returns
    0 on success, -1 on error.
    -
    Note
    hwloc_pid_t is pid_t on Unix platforms, and HANDLE on native Windows platforms.
    - -
    -
    - -

    ◆ hwloc_set_area_membind()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    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 
    )
    -
    - -

    Bind the already-allocated memory identified by (addr, len) to the NUMA node(s) specified by set.

    -

    If HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset. Otherwise it's a cpuset.

    -
    Returns
    0 on success or if len is 0.
    -
    --1 with errno set to ENOSYS if the action is not supported.
    -
    --1 with errno set to EXDEV if the binding cannot be enforced.
    - -
    -
    - -

    ◆ hwloc_set_membind()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_set_membind (hwloc_topology_t topology,
    hwloc_const_bitmap_t set,
    hwloc_membind_policy_t policy,
    int flags 
    )
    -
    - -

    Set the default memory binding policy of the current process or thread to prefer the NUMA node(s) specified by set.

    -

    If neither HWLOC_MEMBIND_PROCESS nor HWLOC_MEMBIND_THREAD is specified, the current process is assumed to be single-threaded. This is the most portable form as it permits hwloc to use either process-based OS functions or thread-based OS functions, depending on which are available.

    -

    If HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset. Otherwise it's a cpuset.

    -
    Returns
    0 on success.
    -
    --1 with errno set to ENOSYS if the action is not supported.
    -
    --1 with errno set to EXDEV if the binding cannot be enforced.
    - -
    -
    - -

    ◆ hwloc_set_proc_membind()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    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 
    )
    -
    - -

    Set the default memory binding policy of the specified process to prefer the NUMA node(s) specified by set.

    -

    If HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset. Otherwise it's a cpuset.

    -
    Returns
    0 on success.
    -
    --1 with errno set to ENOSYS if the action is not supported.
    -
    --1 with errno set to EXDEV if the binding cannot be enforced.
    -
    Note
    hwloc_pid_t is pid_t on Unix platforms, and HANDLE on native Windows platforms.
    - -
    -
    -
    - - - - - - - -
    -
    -Enumerations | -Functions
    -
    Changing the Source of Topology Discovery
    -
    -
    - - - - -

    -Enumerations

    enum  hwloc_topology_components_flag_e { HWLOC_TOPOLOGY_COMPONENTS_FLAG_BLACKLIST - }
     
    - - - - - - - - - - - -

    -Functions

    int hwloc_topology_set_pid (hwloc_topology_t restrict topology, hwloc_pid_t pid)
     
    int hwloc_topology_set_synthetic (hwloc_topology_t restrict topology, const char *restrict description)
     
    int hwloc_topology_set_xml (hwloc_topology_t restrict topology, const char *restrict xmlpath)
     
    int hwloc_topology_set_xmlbuffer (hwloc_topology_t restrict topology, const char *restrict buffer, int size)
     
    int hwloc_topology_set_components (hwloc_topology_t restrict topology, unsigned long flags, const char *restrict name)
     
    -

    Detailed Description

    -

    These functions must be called between hwloc_topology_init() and hwloc_topology_load(). Otherwise, they will return -1 with errno set to EBUSY.

    -

    If none of the functions below is called, the default is to detect all the objects of the machine that the caller is allowed to access.

    -

    This default behavior may also be modified through environment variables if the application did not modify it already. Setting HWLOC_XMLFILE in the environment enforces the discovery from a XML file as if hwloc_topology_set_xml() had been called. Setting HWLOC_SYNTHETIC enforces a synthetic topology as if hwloc_topology_set_synthetic() had been called.

    -

    Finally, HWLOC_THISSYSTEM enforces the return value of hwloc_topology_is_thissystem().

    -

    Enumeration Type Documentation

    - -

    ◆ hwloc_topology_components_flag_e

    - -
    -
    - - - - -
    enum hwloc_topology_components_flag_e
    -
    - -

    Flags to be passed to hwloc_topology_set_components()

    - - -
    Enumerator
    HWLOC_TOPOLOGY_COMPONENTS_FLAG_BLACKLIST 

    Blacklist the target component from being used.

    -
    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_topology_set_components()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_set_components (hwloc_topology_t restrict topology,
    unsigned long flags,
    const char *restrict name 
    )
    -
    - -

    Prevent a discovery component from being used for a topology.

    -

    name is the name of the discovery component that should not be used when loading topology topology. The name is a string such as "cuda".

    -

    For components with multiple phases, it may also be suffixed with the name of a phase, for instance "linux:io".

    -

    flags should be HWLOC_TOPOLOGY_COMPONENTS_FLAG_BLACKLIST.

    -

    This may be used to avoid expensive parts of the discovery process. For instance, CUDA-specific discovery may be expensive and unneeded while generic I/O discovery could still be useful.

    -
    Returns
    0 on success.
    -
    --1 on error, for instance if flags are invalid.
    - -
    -
    - -

    ◆ hwloc_topology_set_pid()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_set_pid (hwloc_topology_t restrict topology,
    hwloc_pid_t pid 
    )
    -
    - -

    Change which process the topology is viewed from.

    -

    On some systems, processes may have different views of the machine, for instance the set of allowed CPUs. By default, hwloc exposes the view from the current process. Calling hwloc_topology_set_pid() permits to make it expose the topology of the machine from the point of view of another process.

    -
    Note
    hwloc_pid_t is pid_t on Unix platforms, and HANDLE on native Windows platforms.
    -
    --1 is returned and errno is set to ENOSYS on platforms that do not support this feature.
    -
    Returns
    0 on success, -1 on error.
    - -
    -
    - -

    ◆ hwloc_topology_set_synthetic()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_set_synthetic (hwloc_topology_t restrict topology,
    const char *restrict description 
    )
    -
    - -

    Enable synthetic topology.

    -

    Gather topology information from the given description, a space-separated string of <type:number> describing the object type and arity at each level. All types may be omitted (space-separated string of numbers) so that hwloc chooses all types according to usual topologies. See also the Synthetic topologies.

    -

    Setting the environment variable HWLOC_SYNTHETIC may also result in this behavior.

    -

    If description was properly parsed and describes a valid topology configuration, this function returns 0. Otherwise -1 is returned and errno is set to EINVAL.

    -

    Note that this function does not actually load topology information; it just tells hwloc where to load it from. You'll still need to invoke hwloc_topology_load() to actually load the topology information.

    -
    Returns
    0 on success.
    -
    --1 with errno set to EINVAL if the description was invalid.
    -
    Note
    For convenience, this backend provides empty binding hooks which just return success.
    -
    -On success, the synthetic component replaces the previously enabled component (if any), but the topology is not actually modified until hwloc_topology_load().
    - -
    -
    - -

    ◆ hwloc_topology_set_xml()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_set_xml (hwloc_topology_t restrict topology,
    const char *restrict xmlpath 
    )
    -
    - -

    Enable XML-file based topology.

    -

    Gather topology information from the XML file given at xmlpath. Setting the environment variable HWLOC_XMLFILE may also result in this behavior. This file may have been generated earlier with hwloc_topology_export_xml() in hwloc/export.h, or lstopo file.xml.

    -

    Note that this function does not actually load topology information; it just tells hwloc where to load it from. You'll still need to invoke hwloc_topology_load() to actually load the topology information.

    -
    Returns
    0 on success.
    -
    --1 with errno set to EINVAL on failure to read the XML file.
    -
    Note
    See also hwloc_topology_set_userdata_import_callback() for importing application-specific object userdata.
    -
    -For convenience, this backend provides empty binding hooks which just return success. To have hwloc still actually call OS-specific hooks, the HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM has to be set to assert that the loaded file is really the underlying system.
    -
    -On success, the XML component replaces the previously enabled component (if any), but the topology is not actually modified until hwloc_topology_load().
    - -
    -
    - -

    ◆ hwloc_topology_set_xmlbuffer()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_set_xmlbuffer (hwloc_topology_t restrict topology,
    const char *restrict buffer,
    int size 
    )
    -
    - -

    Enable XML based topology using a memory buffer (instead of a file, as with hwloc_topology_set_xml()).

    -

    Gather topology information from the XML memory buffer given at buffer and of length size. This buffer may have been filled earlier with hwloc_topology_export_xmlbuffer() in hwloc/export.h.

    -

    Note that this function does not actually load topology information; it just tells hwloc where to load it from. You'll still need to invoke hwloc_topology_load() to actually load the topology information.

    -
    Returns
    0 on success.
    -
    --1 with errno set to EINVAL on failure to read the XML buffer.
    -
    Note
    See also hwloc_topology_set_userdata_import_callback() for importing application-specific object userdata.
    -
    -For convenience, this backend provides empty binding hooks which just return success. To have hwloc still actually call OS-specific hooks, the HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM has to be set to assert that the loaded file is really the underlying system.
    -
    -On success, the XML component replaces the previously enabled component (if any), but the topology is not actually modified until hwloc_topology_load().
    - -
    -
    -
    - - - - - - - -
    -
    -Data Structures | -Enumerations | -Functions
    -
    Topology Detection Configuration and Query
    -
    -
    - - - - - - - - - - - - -

    -Data Structures

    struct  hwloc_topology_discovery_support
     
    struct  hwloc_topology_cpubind_support
     
    struct  hwloc_topology_membind_support
     
    struct  hwloc_topology_misc_support
     
    struct  hwloc_topology_support
     
    - - - - - -

    -Enumerations

    enum  hwloc_topology_flags_e {
    -  HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED -, HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM -, HWLOC_TOPOLOGY_FLAG_THISSYSTEM_ALLOWED_RESOURCES -, HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT = (1UL<<3) -,
    -  HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_CPUBINDING = (1UL<<4) -, HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_MEMBINDING = (1UL<<5) -, HWLOC_TOPOLOGY_FLAG_DONT_CHANGE_BINDING = (1UL<<6) -, HWLOC_TOPOLOGY_FLAG_NO_DISTANCES = (1UL<<7) -,
    -  HWLOC_TOPOLOGY_FLAG_NO_MEMATTRS = (1UL<<8) -, HWLOC_TOPOLOGY_FLAG_NO_CPUKINDS = (1UL<<9) -
    - }
     
    enum  hwloc_type_filter_e { HWLOC_TYPE_FILTER_KEEP_ALL -, HWLOC_TYPE_FILTER_KEEP_NONE -, HWLOC_TYPE_FILTER_KEEP_STRUCTURE -, HWLOC_TYPE_FILTER_KEEP_IMPORTANT - }
     
    - - - - - - - - - - - - - - - - - - - - - - - - - -

    -Functions

    int hwloc_topology_set_flags (hwloc_topology_t topology, unsigned long flags)
     
    unsigned long hwloc_topology_get_flags (hwloc_topology_t topology)
     
    int hwloc_topology_is_thissystem (hwloc_topology_t restrict topology)
     
    const struct hwloc_topology_support * hwloc_topology_get_support (hwloc_topology_t restrict topology)
     
    int hwloc_topology_set_type_filter (hwloc_topology_t topology, hwloc_obj_type_t type, enum hwloc_type_filter_e filter)
     
    int hwloc_topology_get_type_filter (hwloc_topology_t topology, hwloc_obj_type_t type, enum hwloc_type_filter_e *filter)
     
    int hwloc_topology_set_all_types_filter (hwloc_topology_t topology, enum hwloc_type_filter_e filter)
     
    int hwloc_topology_set_cache_types_filter (hwloc_topology_t topology, enum hwloc_type_filter_e filter)
     
    int hwloc_topology_set_icache_types_filter (hwloc_topology_t topology, enum hwloc_type_filter_e filter)
     
    int hwloc_topology_set_io_types_filter (hwloc_topology_t topology, enum hwloc_type_filter_e filter)
     
    void hwloc_topology_set_userdata (hwloc_topology_t topology, const void *userdata)
     
    void * hwloc_topology_get_userdata (hwloc_topology_t topology)
     
    -

    Detailed Description

    -

    Several functions can optionally be called between hwloc_topology_init() and hwloc_topology_load() to configure how the detection should be performed, e.g. to ignore some objects types, define a synthetic topology, etc.

    -

    Enumeration Type Documentation

    - -

    ◆ hwloc_topology_flags_e

    - -
    -
    - - - - -
    enum hwloc_topology_flags_e
    -
    - -

    Flags to be set onto a topology context before load.

    -

    Flags should be given to hwloc_topology_set_flags(). They may also be returned by hwloc_topology_get_flags().

    - - - - - - - - - - - -
    Enumerator
    HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED 

    Detect the whole system, ignore reservations, include disallowed objects.

    -

    Gather all online resources, even if some were disabled by the administrator. For instance, ignore Linux Cgroup/Cpusets and gather all processors and memory nodes. However offline PUs and NUMA nodes are still ignored.

    -

    When this flag is not set, PUs and NUMA nodes that are disallowed are not added to the topology. Parent objects (package, core, cache, etc.) are added only if some of their children are allowed. All existing PUs and NUMA nodes in the topology are allowed. hwloc_topology_get_allowed_cpuset() and hwloc_topology_get_allowed_nodeset() are equal to the root object cpuset and nodeset.

    -

    When this flag is set, the actual sets of allowed PUs and NUMA nodes are given by hwloc_topology_get_allowed_cpuset() and hwloc_topology_get_allowed_nodeset(). They may be smaller than the root object cpuset and nodeset.

    -

    If the current topology is exported to XML and reimported later, this flag should be set again in the reimported topology so that disallowed resources are reimported as well.

    -
    HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM 

    Assume that the selected backend provides the topology for the system on which we are running.

    -

    This forces hwloc_topology_is_thissystem() to return 1, i.e. makes hwloc assume that the selected backend provides the topology for the system on which we are running, even if it is not the OS-specific backend but the XML backend for instance. This means making the binding functions actually call the OS-specific system calls and really do binding, while the XML backend would otherwise provide empty hooks just returning success.

    -

    Setting the environment variable HWLOC_THISSYSTEM may also result in the same behavior.

    -

    This can be used for efficiency reasons to first detect the topology once, save it to an XML file, and quickly reload it later through the XML backend, but still having binding functions actually do bind.

    -
    HWLOC_TOPOLOGY_FLAG_THISSYSTEM_ALLOWED_RESOURCES 

    Get the set of allowed resources from the local operating system even if the topology was loaded from XML or synthetic description.

    -

    If the topology was loaded from XML or from a synthetic string, restrict it by applying the current process restrictions such as Linux Cgroup/Cpuset.

    -

    This is useful when the topology is not loaded directly from the local machine (e.g. for performance reason) and it comes with all resources, while the running process is restricted to only parts of the machine.

    -

    This flag is ignored unless HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM is also set since the loaded topology must match the underlying machine where restrictions will be gathered from.

    -

    Setting the environment variable HWLOC_THISSYSTEM_ALLOWED_RESOURCES would result in the same behavior.

    -
    HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT 

    Import support from the imported topology.

    -

    When importing a XML topology from a remote machine, binding is disabled by default (see HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM). This disabling is also marked by putting zeroes in the corresponding supported feature bits reported by hwloc_topology_get_support().

    -

    The flag HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT actually imports support bits from the remote machine. It also sets the flag imported_support in the struct hwloc_topology_misc_support array. If the imported XML did not contain any support information (exporter hwloc is too old), this flag is not set.

    -

    Note that these supported features are only relevant for the hwloc installation that actually exported the XML topology (it may vary with the operating system, or with how hwloc was compiled).

    -

    Note that setting this flag however does not enable binding for the locally imported hwloc topology, it only reports what the remote hwloc and machine support.

    -
    HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_CPUBINDING 

    Do not consider resources outside of the process CPU binding.

    -

    If the binding of the process is limited to a subset of cores, ignore the other cores during discovery.

    -

    The resulting topology is identical to what a call to hwloc_topology_restrict() would generate, but this flag also prevents hwloc from ever touching other resources during the discovery.

    -

    This flag especially tells the x86 backend to never temporarily rebind a thread on any excluded core. This is useful on Windows because such temporary rebinding can change the process binding. Another use-case is to avoid cores that would not be able to perform the hwloc discovery anytime soon because they are busy executing some high-priority real-time tasks.

    -

    If process CPU binding is not supported, the thread CPU binding is considered instead if supported, or the flag is ignored.

    -

    This flag requires HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM as well since binding support is required.

    -
    HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_MEMBINDING 

    Do not consider resources outside of the process memory binding.

    -

    If the binding of the process is limited to a subset of NUMA nodes, ignore the other NUMA nodes during discovery.

    -

    The resulting topology is identical to what a call to hwloc_topology_restrict() would generate, but this flag also prevents hwloc from ever touching other resources during the discovery.

    -

    This flag is meant to be used together with HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_CPUBINDING when both cores and NUMA nodes should be ignored outside of the process binding.

    -

    If process memory binding is not supported, the thread memory binding is considered instead if supported, or the flag is ignored.

    -

    This flag requires HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM as well since binding support is required.

    -
    HWLOC_TOPOLOGY_FLAG_DONT_CHANGE_BINDING 

    Do not ever modify the process or thread binding during discovery.

    -

    This flag disables all hwloc discovery steps that require a change of the process or thread binding. This currently only affects the x86 backend which gets entirely disabled.

    -

    This is useful when hwloc_topology_load() is called while the application also creates additional threads or modifies the binding.

    -

    This flag is also a strict way to make sure the process binding will not change to due thread binding changes on Windows (see HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_CPUBINDING).

    -
    HWLOC_TOPOLOGY_FLAG_NO_DISTANCES 

    Ignore distances.

    -

    Ignore distance information from the operating systems (and from XML) and hence do not use distances for grouping.

    -
    HWLOC_TOPOLOGY_FLAG_NO_MEMATTRS 

    Ignore memory attributes.

    -

    Ignore memory attribues from the operating systems (and from XML).

    -
    HWLOC_TOPOLOGY_FLAG_NO_CPUKINDS 

    Ignore CPU Kinds.

    -

    Ignore CPU kind information from the operating systems (and from XML).

    -
    - -
    -
    - -

    ◆ hwloc_type_filter_e

    - -
    -
    - - - - -
    enum hwloc_type_filter_e
    -
    - -

    Type filtering flags.

    -

    By default, most objects are kept (HWLOC_TYPE_FILTER_KEEP_ALL). Instruction caches, I/O and Misc objects are ignored by default (HWLOC_TYPE_FILTER_KEEP_NONE). Die and Group levels are ignored unless they bring structure (HWLOC_TYPE_FILTER_KEEP_STRUCTURE).

    -

    Note that group objects are also ignored individually (without the entire level) when they do not bring structure.

    - - - - - -
    Enumerator
    HWLOC_TYPE_FILTER_KEEP_ALL 

    Keep all objects of this type.

    -

    Cannot be set for HWLOC_OBJ_GROUP (groups are designed only to add more structure to the topology).

    -
    HWLOC_TYPE_FILTER_KEEP_NONE 

    Ignore all objects of this type.

    -

    The bottom-level type HWLOC_OBJ_PU, the HWLOC_OBJ_NUMANODE type, and the top-level type HWLOC_OBJ_MACHINE may not be ignored.

    -
    HWLOC_TYPE_FILTER_KEEP_STRUCTURE 

    Only ignore objects if their entire level does not bring any structure.

    -

    Keep the entire level of objects if at least one of these objects adds structure to the topology. An object brings structure when it has multiple children and it is not the only child of its parent.

    -

    If all objects in the level are the only child of their parent, and if none of them has multiple children, the entire level is removed.

    -

    Cannot be set for I/O and Misc objects since the topology structure does not matter there.

    -
    HWLOC_TYPE_FILTER_KEEP_IMPORTANT 

    Only keep likely-important objects of the given type.

    -

    It is only useful for I/O object types. For HWLOC_OBJ_PCI_DEVICE and HWLOC_OBJ_OS_DEVICE, it means that only objects of major/common kinds are kept (storage, network, OpenFabrics, CUDA, OpenCL, RSMI, NVML, and displays). Also, only OS devices directly attached on PCI (e.g. no USB) are reported. For HWLOC_OBJ_BRIDGE, it means that bridges are kept only if they have children.

    -

    This flag equivalent to HWLOC_TYPE_FILTER_KEEP_ALL for Normal, Memory and Misc types since they are likely important.

    -
    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_topology_get_flags()

    - -
    -
    - - - - - - - - -
    unsigned long hwloc_topology_get_flags (hwloc_topology_t topology)
    -
    - -

    Get OR'ed flags of a topology.

    -

    Get the OR'ed set of hwloc_topology_flags_e of a topology.

    -

    If hwloc_topology_set_flags() was not called earlier, no flags are set (0 is returned).

    -
    Returns
    the flags previously set with hwloc_topology_set_flags().
    -
    Note
    This function may also be called after hwloc_topology_load().
    - -
    -
    - -

    ◆ hwloc_topology_get_support()

    - -
    -
    - - - - - - - - -
    const struct hwloc_topology_support * hwloc_topology_get_support (hwloc_topology_t restrict topology)
    -
    - -

    Retrieve the topology support.

    -

    Each flag indicates whether a feature is supported. If set to 0, the feature is not supported. If set to 1, the feature is supported, but the corresponding call may still fail in some corner cases.

    -

    These features are also listed by hwloc-info --support

    -

    The reported features are what the current topology supports on the current machine. If the topology was exported to XML from another machine and later imported here, support still describes what is supported for this imported topology after import. By default, binding will be reported as unsupported in this case (see HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM).

    -

    Topology flag HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT may be used to report the supported features of the original remote machine instead. If it was successfully imported, imported_support will be set in the struct hwloc_topology_misc_support array.

    -
    Returns
    A pointer to a support structure.
    -
    Note
    The function cannot return NULL.
    -
    -The returned pointer should not be freed, it belongs to the hwloc library.
    -
    -This function may be called before or after hwloc_topology_load() but the support structure only contains valid information after.
    - -
    -
    - -

    ◆ hwloc_topology_get_type_filter()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_get_type_filter (hwloc_topology_t topology,
    hwloc_obj_type_t type,
    enum hwloc_type_filter_e * filter 
    )
    -
    - -

    Get the current filtering for the given object type.

    -
    Returns
    0 on success, -1 on error.
    - -
    -
    - -

    ◆ hwloc_topology_get_userdata()

    - -
    -
    - - - - - - - - -
    void * hwloc_topology_get_userdata (hwloc_topology_t topology)
    -
    - -

    Retrieve the topology-specific userdata pointer.

    -

    Retrieve the application-given private data pointer that was previously set with hwloc_topology_set_userdata().

    -
    Returns
    A pointer to the private-data if any.
    -
    -NULL if no private-data was previoulsy set.
    - -
    -
    - -

    ◆ hwloc_topology_is_thissystem()

    - -
    -
    - - - - - - - - -
    int hwloc_topology_is_thissystem (hwloc_topology_t restrict topology)
    -
    - -

    Does the topology context come from this system?

    -
    Returns
    1 if this topology context was built using the system running this program.
    -
    -0 instead (for instance if using another file-system root, a XML topology file, or a synthetic topology).
    -
    Note
    This function may also be called after hwloc_topology_load().
    - -
    -
    - -

    ◆ hwloc_topology_set_all_types_filter()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_set_all_types_filter (hwloc_topology_t topology,
    enum hwloc_type_filter_e filter 
    )
    -
    - -

    Set the filtering for all object types.

    -

    If some types do not support this filtering, they are silently ignored.

    -
    Returns
    0 on success, -1 on error.
    - -
    -
    - -

    ◆ hwloc_topology_set_cache_types_filter()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_set_cache_types_filter (hwloc_topology_t topology,
    enum hwloc_type_filter_e filter 
    )
    -
    - -

    Set the filtering for all CPU cache object types.

    -

    Memory-side caches are not involved since they are not CPU caches.

    -
    Returns
    0 on success, -1 on error.
    - -
    -
    - -

    ◆ hwloc_topology_set_flags()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_set_flags (hwloc_topology_t topology,
    unsigned long flags 
    )
    -
    - -

    Set OR'ed flags to non-yet-loaded topology.

    -

    Set a OR'ed set of hwloc_topology_flags_e onto a topology that was not yet loaded.

    -

    If this function is called multiple times, the last invocation will erase and replace the set of flags that was previously set.

    -

    By default, no flags are set (0).

    -

    The flags set in a topology may be retrieved with hwloc_topology_get_flags().

    -
    Returns
    0 on success.
    -
    --1 on error, for instance if flags are invalid.
    - -
    -
    - -

    ◆ hwloc_topology_set_icache_types_filter()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_set_icache_types_filter (hwloc_topology_t topology,
    enum hwloc_type_filter_e filter 
    )
    -
    - -

    Set the filtering for all CPU instruction cache object types.

    -

    Memory-side caches are not involved since they are not CPU caches.

    -
    Returns
    0 on success, -1 on error.
    - -
    -
    - -

    ◆ hwloc_topology_set_io_types_filter()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_set_io_types_filter (hwloc_topology_t topology,
    enum hwloc_type_filter_e filter 
    )
    -
    - -

    Set the filtering for all I/O object types.

    -
    Returns
    0 on success, -1 on error.
    - -
    -
    - -

    ◆ hwloc_topology_set_type_filter()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_set_type_filter (hwloc_topology_t topology,
    hwloc_obj_type_t type,
    enum hwloc_type_filter_e filter 
    )
    -
    - -

    Set the filtering for the given object type.

    -
    Returns
    0 on success, -1 on error.
    - -
    -
    - -

    ◆ hwloc_topology_set_userdata()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    void hwloc_topology_set_userdata (hwloc_topology_t topology,
    const void * userdata 
    )
    -
    - -

    Set the topology-specific userdata pointer.

    -

    Each topology may store one application-given private data pointer. It is initialized to NULL. hwloc will never modify it.

    -

    Use it as you wish, after hwloc_topology_init() and until hwloc_topolog_destroy().

    -

    This pointer is not exported to XML.

    - -
    -
    -
    - - - - - - - -
    -
    -Enumerations | -Functions
    -
    Modifying a loaded Topology
    -
    -
    - - - - - - -

    -Enumerations

    enum  hwloc_restrict_flags_e {
    -  HWLOC_RESTRICT_FLAG_REMOVE_CPULESS -, HWLOC_RESTRICT_FLAG_BYNODESET = (1UL<<3) -, HWLOC_RESTRICT_FLAG_REMOVE_MEMLESS -, HWLOC_RESTRICT_FLAG_ADAPT_MISC -,
    -  HWLOC_RESTRICT_FLAG_ADAPT_IO -
    - }
     
    enum  hwloc_allow_flags_e { HWLOC_ALLOW_FLAG_ALL -, HWLOC_ALLOW_FLAG_LOCAL_RESTRICTIONS -, HWLOC_ALLOW_FLAG_CUSTOM - }
     
    - - - - - - - - - - - - - - - -

    -Functions

    int hwloc_topology_restrict (hwloc_topology_t restrict topology, hwloc_const_bitmap_t set, unsigned long flags)
     
    int hwloc_topology_allow (hwloc_topology_t restrict topology, hwloc_const_cpuset_t cpuset, hwloc_const_nodeset_t nodeset, unsigned long flags)
     
    hwloc_obj_t hwloc_topology_insert_misc_object (hwloc_topology_t topology, hwloc_obj_t parent, const char *name)
     
    hwloc_obj_t hwloc_topology_alloc_group_object (hwloc_topology_t topology)
     
    hwloc_obj_t hwloc_topology_insert_group_object (hwloc_topology_t topology, hwloc_obj_t group)
     
    int hwloc_obj_add_other_obj_sets (hwloc_obj_t dst, hwloc_obj_t src)
     
    int hwloc_topology_refresh (hwloc_topology_t topology)
     
    -

    Detailed Description

    -

    Enumeration Type Documentation

    - -

    ◆ hwloc_allow_flags_e

    - -
    -
    - - - - -
    enum hwloc_allow_flags_e
    -
    - -

    Flags to be given to hwloc_topology_allow().

    - - - - -
    Enumerator
    HWLOC_ALLOW_FLAG_ALL 

    Mark all objects as allowed in the topology.

    -

    cpuset and nođeset given to hwloc_topology_allow() must be NULL.

    -
    HWLOC_ALLOW_FLAG_LOCAL_RESTRICTIONS 

    Only allow objects that are available to the current process.

    -

    The topology must have HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM so that the set of available resources can actually be retrieved from the operating system.

    -

    cpuset and nođeset given to hwloc_topology_allow() must be NULL.

    -
    HWLOC_ALLOW_FLAG_CUSTOM 

    Allow a custom set of objects, given to hwloc_topology_allow() as cpuset and/or nodeset parameters.

    -
    - -
    -
    - -

    ◆ hwloc_restrict_flags_e

    - -
    -
    - - - - -
    enum hwloc_restrict_flags_e
    -
    - -

    Flags to be given to hwloc_topology_restrict().

    - - - - - - -
    Enumerator
    HWLOC_RESTRICT_FLAG_REMOVE_CPULESS 

    Remove all objects that became CPU-less. By default, only objects that contain no PU and no memory are removed. This flag may not be used with HWLOC_RESTRICT_FLAG_BYNODESET.

    -
    HWLOC_RESTRICT_FLAG_BYNODESET 

    Restrict by nodeset instead of CPU set. Only keep objects whose nodeset is included or partially included in the given set. This flag may not be used with HWLOC_RESTRICT_FLAG_REMOVE_CPULESS.

    -
    HWLOC_RESTRICT_FLAG_REMOVE_MEMLESS 

    Remove all objects that became Memory-less. By default, only objects that contain no PU and no memory are removed. This flag may only be used with HWLOC_RESTRICT_FLAG_BYNODESET.

    -
    HWLOC_RESTRICT_FLAG_ADAPT_MISC 

    Move Misc objects to ancestors if their parents are removed during restriction. If this flag is not set, Misc objects are removed when their parents are removed.

    -
    HWLOC_RESTRICT_FLAG_ADAPT_IO 

    Move I/O objects to ancestors if their parents are removed during restriction. If this flag is not set, I/O devices and bridges are removed when their parents are removed.

    -
    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_obj_add_other_obj_sets()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_obj_add_other_obj_sets (hwloc_obj_t dst,
    hwloc_obj_t src 
    )
    -
    - -

    Setup object cpusets/nodesets by OR'ing another object's sets.

    -

    For each defined cpuset or nodeset in src, allocate the corresponding set in dst and add src to it by OR'ing sets.

    -

    This function is convenient between hwloc_topology_alloc_group_object() and hwloc_topology_insert_group_object(). It builds the sets of the new Group that will be inserted as a new intermediate parent of several objects.

    -
    Returns
    0 on success.
    -
    --1 with errno set to ENOMEM if some internal reallocation failed.
    - -
    -
    - -

    ◆ hwloc_topology_alloc_group_object()

    - -
    -
    - - - - - - - - -
    hwloc_obj_t hwloc_topology_alloc_group_object (hwloc_topology_t topology)
    -
    - -

    Allocate a Group object to insert later with hwloc_topology_insert_group_object().

    -

    This function returns a new Group object.

    -

    The caller should (at least) initialize its sets before inserting the object in the topology. See hwloc_topology_insert_group_object().

    -
    Returns
    The allocated object on success.
    -
    -NULL on error.
    - -
    -
    - -

    ◆ hwloc_topology_allow()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_allow (hwloc_topology_t restrict topology,
    hwloc_const_cpuset_t cpuset,
    hwloc_const_nodeset_t nodeset,
    unsigned long flags 
    )
    -
    - -

    Change the sets of allowed PUs and NUMA nodes in the topology.

    -

    This function only works if the HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED was set on the topology. It does not modify any object, it only changes the sets returned by hwloc_topology_get_allowed_cpuset() and hwloc_topology_get_allowed_nodeset().

    -

    It is notably useful when importing a topology from another process running in a different Linux Cgroup.

    -

    flags must be set to one flag among hwloc_allow_flags_e.

    -
    Returns
    0 on success, -1 on error.
    -
    Note
    Removing objects from a topology should rather be performed with hwloc_topology_restrict().
    - -
    -
    - -

    ◆ hwloc_topology_insert_group_object()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    hwloc_obj_t hwloc_topology_insert_group_object (hwloc_topology_t topology,
    hwloc_obj_t group 
    )
    -
    - -

    Add more structure to the topology by adding an intermediate Group.

    -

    The caller should first allocate a new Group object with hwloc_topology_alloc_group_object(). Then it must setup at least one of its CPU or node sets to specify the final location of the Group in the topology. Then the object can be passed to this function for actual insertion in the topology.

    -

    Either the cpuset or nodeset field (or both, if compatible) must be set to a non-empty bitmap. The complete_cpuset or complete_nodeset may be set instead if inserting with respect to the complete topology (including disallowed, offline or unknown objects). If grouping several objects, hwloc_obj_add_other_obj_sets() is an easy way to build the Group sets iteratively. These sets cannot be larger than the current topology, or they would get restricted silently. The core will setup the other sets after actual insertion.

    -

    The subtype object attribute may be defined (to a dynamically allocated string) to display something else than "Group" as the type name for this object in lstopo. Custom name/value info pairs may be added with hwloc_obj_add_info() after insertion.

    -

    The group dont_merge attribute may be set to 1 to prevent the hwloc core from ever merging this object with another hierarchically-identical object. This is useful when the Group itself describes an important feature that cannot be exposed anywhere else in the hierarchy.

    -

    The group kind attribute may be set to a high value such as 0xffffffff to tell hwloc that this new Group should always be discarded in favor of any existing Group with the same locality.

    -
    Returns
    The inserted object if it was properly inserted.
    -
    -An existing object if the Group was merged or discarded because the topology already contained an object at the same location (the Group did not add any hierarchy information).
    -
    -NULL if the insertion failed because of conflicting sets in topology tree.
    -
    -NULL if Group objects are filtered-out of the topology (HWLOC_TYPE_FILTER_KEEP_NONE).
    -
    -NULL if the object was discarded because no set was initialized in the Group before insert, or all of them were empty.
    - -
    -
    - -

    ◆ hwloc_topology_insert_misc_object()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    hwloc_obj_t hwloc_topology_insert_misc_object (hwloc_topology_t topology,
    hwloc_obj_t parent,
    const char * name 
    )
    -
    - -

    Add a MISC object as a leaf of the topology.

    -

    A new MISC object will be created and inserted into the topology at the position given by parent. It is appended to the list of existing Misc children, without ever adding any intermediate hierarchy level. This is useful for annotating the topology without actually changing the hierarchy.

    -

    name is supposed to be unique across all Misc objects in the topology. It will be duplicated to setup the new object attributes.

    -

    The new leaf object will not have any cpuset.

    -
    Returns
    the newly-created object
    -
    -NULL on error.
    -
    -NULL if Misc objects are filtered-out of the topology (HWLOC_TYPE_FILTER_KEEP_NONE).
    -
    Note
    If name contains some non-printable characters, they will be dropped when exporting to XML, see hwloc_topology_export_xml() in hwloc/export.h.
    - -
    -
    - -

    ◆ hwloc_topology_refresh()

    - -
    -
    - - - - - - - - -
    int hwloc_topology_refresh (hwloc_topology_t topology)
    -
    - -

    Refresh internal structures after topology modification.

    -

    Modifying the topology (by restricting, adding objects, modifying structures such as distances or memory attributes, etc.) may cause some internal caches to become invalid. These caches are automatically refreshed when accessed but this refreshing is not thread-safe.

    -

    This function is not thread-safe either, but it is a good way to end a non-thread-safe phase of topology modification. Once this refresh is done, multiple threads may concurrently consult the topology, objects, distances, attributes, etc.

    -

    See also Thread Safety

    -
    Returns
    0 on success.
    -
    --1 on error, for instance if some internal reallocation failed.
    - -
    -
    - -

    ◆ hwloc_topology_restrict()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_restrict (hwloc_topology_t restrict topology,
    hwloc_const_bitmap_t set,
    unsigned long flags 
    )
    -
    - -

    Restrict the topology to the given CPU set or nodeset.

    -

    Topology topology is modified so as to remove all objects that are not included (or partially included) in the CPU set set. All objects CPU and node sets are restricted accordingly.

    -

    If HWLOC_RESTRICT_FLAG_BYNODESET is passed in flags, set is considered a nodeset instead of a CPU set.

    -

    flags is a OR'ed set of hwloc_restrict_flags_e.

    -
    Note
    This call may not be reverted by restricting back to a larger set. Once dropped during restriction, objects may not be brought back, except by loading another topology with hwloc_topology_load().
    -
    Returns
    0 on success.
    -
    --1 with errno set to EINVAL if the input set is invalid. The topology is not modified in this case.
    -
    --1 with errno set to ENOMEM on failure to allocate internal data. The topology is reinitialized in this case. It should be either destroyed with hwloc_topology_destroy() or configured and loaded again.
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    Finding Objects inside a CPU set
    -
    -
    - - - - - - - - - - - - - - - - - - - - -

    -Functions

    static hwloc_obj_t hwloc_get_first_largest_obj_inside_cpuset (hwloc_topology_t topology, hwloc_const_cpuset_t set)
     
    int hwloc_get_largest_objs_inside_cpuset (hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_t *restrict objs, int max)
     
    static hwloc_obj_t hwloc_get_next_obj_inside_cpuset_by_depth (hwloc_topology_t topology, hwloc_const_cpuset_t set, int depth, hwloc_obj_t prev)
     
    static hwloc_obj_t hwloc_get_next_obj_inside_cpuset_by_type (hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_type_t type, hwloc_obj_t prev)
     
    static hwloc_obj_t hwloc_get_obj_inside_cpuset_by_depth (hwloc_topology_t topology, hwloc_const_cpuset_t set, int depth, unsigned idx)
     
    static hwloc_obj_t hwloc_get_obj_inside_cpuset_by_type (hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_type_t type, unsigned idx)
     
    static unsigned hwloc_get_nbobjs_inside_cpuset_by_depth (hwloc_topology_t topology, hwloc_const_cpuset_t set, int depth)
     
    static int hwloc_get_nbobjs_inside_cpuset_by_type (hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_type_t type)
     
    static int hwloc_get_obj_index_inside_cpuset (hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_t obj)
     
    -

    Detailed Description

    -

    Function Documentation

    - -

    ◆ hwloc_get_first_largest_obj_inside_cpuset()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_first_largest_obj_inside_cpuset (hwloc_topology_t topology,
    hwloc_const_cpuset_t set 
    )
    -     		-inlinestatic
    -
    - -

    Get the first largest object included in the given cpuset set.

    -
    Returns
    the first object that is included in set and whose parent is not.
    -
    -NULL if no such object exists.
    -

    This is convenient for iterating over all largest objects within a CPU set by doing a loop getting the first largest object and clearing its CPU set from the remaining CPU set.

    - -
    -
    - -

    ◆ hwloc_get_largest_objs_inside_cpuset()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_get_largest_objs_inside_cpuset (hwloc_topology_t topology,
    hwloc_const_cpuset_t set,
    hwloc_obj_t *restrict objs,
    int max 
    )
    -
    - -

    Get the set of largest objects covering exactly a given cpuset set.

    -
    Returns
    the number of objects returned in objs.
    -
    --1 if no set of objects may cover that cpuset.
    - -
    -
    - -

    ◆ hwloc_get_nbobjs_inside_cpuset_by_depth()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static unsigned hwloc_get_nbobjs_inside_cpuset_by_depth (hwloc_topology_t topology,
    hwloc_const_cpuset_t set,
    int depth 
    )
    -     		-inlinestatic
    -
    - -

    Return the number of objects at depth depth included in CPU set set.

    -
    Returns
    the number of objects.
    -
    -0 if the depth is invalid.
    -
    Note
    Objects with empty CPU sets are ignored (otherwise they would be considered included in any given set).
    -
    -This function cannot work if objects at the given depth do not have CPU sets (I/O or Misc objects).
    - -
    -
    - -

    ◆ hwloc_get_nbobjs_inside_cpuset_by_type()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_get_nbobjs_inside_cpuset_by_type (hwloc_topology_t topology,
    hwloc_const_cpuset_t set,
    hwloc_obj_type_t type 
    )
    -     		-inlinestatic
    -
    - -

    Return the number of objects of type type included in CPU set set.

    -
    Returns
    the number of objects.
    -
    -0 if there are no objects of that type in the topology.
    -
    --1 if there are multiple levels of objects of that type, the caller should fallback to hwloc_get_nbobjs_inside_cpuset_by_depth().
    -
    Note
    Objects with empty CPU sets are ignored (otherwise they would be considered included in any given set).
    -
    -This function cannot work if objects of the given type do not have CPU sets (I/O objects).
    - -
    -
    - -

    ◆ hwloc_get_next_obj_inside_cpuset_by_depth()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_next_obj_inside_cpuset_by_depth (hwloc_topology_t topology,
    hwloc_const_cpuset_t set,
    int depth,
    hwloc_obj_t prev 
    )
    -     		-inlinestatic
    -
    - -

    Return the next object at depth depth included in CPU set set.

    -

    The next invokation should pass the previous return value in prev so as to obtain the next object in set.

    -
    Returns
    the first object at depth depth included in set if prev is NULL.
    -
    -the next object at depth depth included in set if prev is not NULL.
    -
    -NULL if there is no next object.
    -
    Note
    Objects with empty CPU sets are ignored (otherwise they would be considered included in any given set).
    -
    -This function cannot work if objects at the given depth do not have CPU sets (I/O or Misc objects).
    - -
    -
    - -

    ◆ hwloc_get_next_obj_inside_cpuset_by_type()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_next_obj_inside_cpuset_by_type (hwloc_topology_t topology,
    hwloc_const_cpuset_t set,
    hwloc_obj_type_t type,
    hwloc_obj_t prev 
    )
    -     		-inlinestatic
    -
    - -

    Return the next object of type type included in CPU set set.

    -

    The next invokation should pass the previous return value in prev so as to obtain the next object in set.

    -
    Returns
    the first object of type type included in set if prev is NULL.
    -
    -the next object of type type included in set if prev is not NULL.
    -
    -NULL if there is no next object.
    -
    -NULL if there is no depth for the given type.
    -
    -NULL if there are multiple depths for the given type, the caller should fallback to hwloc_get_next_obj_inside_cpuset_by_depth().
    -
    Note
    Objects with empty CPU sets are ignored (otherwise they would be considered included in any given set).
    -
    -This function cannot work if objects of the given type do not have CPU sets (I/O or Misc objects).
    - -
    -
    - -

    ◆ hwloc_get_obj_index_inside_cpuset()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_get_obj_index_inside_cpuset (hwloc_topology_t topology,
    hwloc_const_cpuset_t set,
    hwloc_obj_t obj 
    )
    -     		-inlinestatic
    -
    - -

    Return the logical index among the objects included in CPU set set.

    -

    Consult all objects in the same level as obj and inside CPU set set in the logical order, and return the index of obj within them. If set covers the entire topology, this is the logical index of obj. Otherwise, this is similar to a logical index within the part of the topology defined by CPU set set.

    -
    Returns
    the logical index among the objects included in the set if any.
    -
    --1 if the object is not included in the set.
    -
    Note
    Objects with empty CPU sets are ignored (otherwise they would be considered included in any given set).
    -
    -This function cannot work if obj does not have CPU sets (I/O objects).
    - -
    -
    - -

    ◆ hwloc_get_obj_inside_cpuset_by_depth()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_obj_inside_cpuset_by_depth (hwloc_topology_t topology,
    hwloc_const_cpuset_t set,
    int depth,
    unsigned idx 
    )
    -     		-inlinestatic
    -
    - -

    Return the (logically) idx -th object at depth depth included in CPU set set.

    -
    Returns
    the object if any, NULL otherwise.
    -
    Note
    Objects with empty CPU sets are ignored (otherwise they would be considered included in any given set).
    -
    -This function cannot work if objects at the given depth do not have CPU sets (I/O or Misc objects).
    - -
    -
    - -

    ◆ hwloc_get_obj_inside_cpuset_by_type()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_obj_inside_cpuset_by_type (hwloc_topology_t topology,
    hwloc_const_cpuset_t set,
    hwloc_obj_type_t type,
    unsigned idx 
    )
    -     		-inlinestatic
    -
    - -

    Return the idx -th object of type type included in CPU set set.

    -
    Returns
    the object if any.
    -
    -NULL if there is no such object.
    -
    -NULL if there is no depth for given type.
    -
    -NULL if there are multiple depths for given type, the caller should fallback to hwloc_get_obj_inside_cpuset_by_depth().
    -
    Note
    Objects with empty CPU sets are ignored (otherwise they would be considered included in any given set).
    -
    -This function cannot work if objects of the given type do not have CPU sets (I/O or Misc objects).
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    Finding Objects covering at least CPU set
    -
    -
    - - - - - - - - - - -

    -Functions

    static hwloc_obj_t hwloc_get_child_covering_cpuset (hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_t parent)
     
    static hwloc_obj_t hwloc_get_obj_covering_cpuset (hwloc_topology_t topology, hwloc_const_cpuset_t set)
     
    static hwloc_obj_t hwloc_get_next_obj_covering_cpuset_by_depth (hwloc_topology_t topology, hwloc_const_cpuset_t set, int depth, hwloc_obj_t prev)
     
    static hwloc_obj_t hwloc_get_next_obj_covering_cpuset_by_type (hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_type_t type, hwloc_obj_t prev)
     
    -

    Detailed Description

    -

    Function Documentation

    - -

    ◆ hwloc_get_child_covering_cpuset()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_child_covering_cpuset (hwloc_topology_t topology,
    hwloc_const_cpuset_t set,
    hwloc_obj_t parent 
    )
    -     		-inlinestatic
    -
    - -

    Get the child covering at least CPU set set.

    -
    Returns
    the child that covers the set entirely.
    -
    -NULL if no child matches or if set is empty.
    -
    Note
    This function cannot work if parent does not have a CPU set (I/O or Misc objects).
    - -
    -
    - -

    ◆ hwloc_get_next_obj_covering_cpuset_by_depth()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_next_obj_covering_cpuset_by_depth (hwloc_topology_t topology,
    hwloc_const_cpuset_t set,
    int depth,
    hwloc_obj_t prev 
    )
    -     		-inlinestatic
    -
    - -

    Iterate through same-depth objects covering at least CPU set set.

    -

    The next invokation should pass the previous return value in prev so as to obtain the next object covering at least another part of set.

    -
    Returns
    the first object at depth depth covering at least part of CPU set set if object prev is NULL.
    -
    -the next one if prev is not NULL.
    -
    -NULL if there is no next object.
    -
    Note
    This function cannot work if objects at the given depth do not have CPU sets (I/O or Misc objects).
    - -
    -
    - -

    ◆ hwloc_get_next_obj_covering_cpuset_by_type()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_next_obj_covering_cpuset_by_type (hwloc_topology_t topology,
    hwloc_const_cpuset_t set,
    hwloc_obj_type_t type,
    hwloc_obj_t prev 
    )
    -     		-inlinestatic
    -
    - -

    Iterate through same-type objects covering at least CPU set set.

    -

    The next invokation should pass the previous return value in prev so as to obtain the next object of type type covering at least another part of set.

    -
    Returns
    the first object of type type covering at least part of CPU set set if object prev is NULL.
    -
    -the next one if prev is not NULL.
    -
    -NULL if there is no next object.
    -
    -NULL if there is no depth for the given type.
    -
    -NULL if there are multiple depths for the given type, the caller should fallback to hwloc_get_next_obj_covering_cpuset_by_depth().
    -
    Note
    This function cannot work if objects of the given type do not have CPU sets (I/O or Misc objects).
    - -
    -
    - -

    ◆ hwloc_get_obj_covering_cpuset()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_obj_covering_cpuset (hwloc_topology_t topology,
    hwloc_const_cpuset_t set 
    )
    -     		-inlinestatic
    -
    - -

    Get the lowest object covering at least CPU set set.

    -
    Returns
    the lowest object covering the set entirely.
    -
    -NULL if no object matches or if set is empty.
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    Looking at Ancestor and Child Objects
    -
    -
    - - - - - - - - - - - - -

    -Functions

    static hwloc_obj_t hwloc_get_ancestor_obj_by_depth (hwloc_topology_t topology, int depth, hwloc_obj_t obj)
     
    static hwloc_obj_t hwloc_get_ancestor_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, hwloc_obj_t obj)
     
    static hwloc_obj_t hwloc_get_common_ancestor_obj (hwloc_topology_t topology, hwloc_obj_t obj1, hwloc_obj_t obj2)
     
    static int hwloc_obj_is_in_subtree (hwloc_topology_t topology, hwloc_obj_t obj, hwloc_obj_t subtree_root)
     
    static hwloc_obj_t hwloc_get_next_child (hwloc_topology_t topology, hwloc_obj_t parent, hwloc_obj_t prev)
     
    -

    Detailed Description

    -

    Be sure to see the figure in Terms and Definitions that shows a complete topology tree, including depths, child/sibling/cousin relationships, and an example of an asymmetric topology where one package has fewer caches than its peers.

    -

    Function Documentation

    - -

    ◆ hwloc_get_ancestor_obj_by_depth()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_ancestor_obj_by_depth (hwloc_topology_t topology,
    int depth,
    hwloc_obj_t obj 
    )
    -     		-inlinestatic
    -
    - -

    Returns the ancestor object of obj at depth depth.

    -
    Returns
    the ancestor if any.
    -
    -NULL if no such ancestor exists.
    -
    Note
    depth should not be the depth of PU or NUMA objects since they are ancestors of no objects (except Misc or I/O). This function rather expects an intermediate level depth, such as the depth of Packages, Cores, or Caches.
    - -
    -
    - -

    ◆ hwloc_get_ancestor_obj_by_type()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_ancestor_obj_by_type (hwloc_topology_t topology,
    hwloc_obj_type_t type,
    hwloc_obj_t obj 
    )
    -     		-inlinestatic
    -
    - -

    Returns the ancestor object of obj with type type.

    -
    Returns
    the ancestor if any.
    -
    -NULL if no such ancestor exists.
    -
    Note
    if multiple matching ancestors exist (e.g. multiple levels of HWLOC_OBJ_GROUP) the lowest one is returned.
    -
    -type should not be HWLOC_OBJ_PU or HWLOC_OBJ_NUMANODE since these objects are ancestors of no objects (except Misc or I/O). This function rather expects an intermediate object type, such as HWLOC_OBJ_PACKAGE, HWLOC_OBJ_CORE, etc.
    - -
    -
    - -

    ◆ hwloc_get_common_ancestor_obj()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_common_ancestor_obj (hwloc_topology_t topology,
    hwloc_obj_t obj1,
    hwloc_obj_t obj2 
    )
    -     		-inlinestatic
    -
    - -

    Returns the common parent object to objects obj1 and obj2.

    -
    Returns
    the common ancestor.
    -
    Note
    This function cannot return NULL.
    - -
    -
    - -

    ◆ hwloc_get_next_child()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_next_child (hwloc_topology_t topology,
    hwloc_obj_t parent,
    hwloc_obj_t prev 
    )
    -     		-inlinestatic
    -
    - -

    Return the next child.

    -

    Return the next child among the normal children list, then among the memory children list, then among the I/O children list, then among the Misc children list.

    -
    Returns
    the first child if prev is NULL.
    -
    -the next child if prev is not NULL.
    -
    -NULL when there is no next child.
    - -
    -
    - -

    ◆ hwloc_obj_is_in_subtree()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_obj_is_in_subtree (hwloc_topology_t topology,
    hwloc_obj_t obj,
    hwloc_obj_t subtree_root 
    )
    -     		-inlinestatic
    -
    - -

    Returns true if obj is inside the subtree beginning with ancestor object subtree_root.

    -
    Returns
    1 is the object is in the subtree, 0 otherwise.
    -
    Note
    This function cannot work if obj and subtree_root objects do not have CPU sets (I/O or Misc objects).
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    Kinds of object Type
    -
    -
    - - - - - - - - - - - - - - -

    -Functions

    int hwloc_obj_type_is_normal (hwloc_obj_type_t type)
     
    int hwloc_obj_type_is_io (hwloc_obj_type_t type)
     
    int hwloc_obj_type_is_memory (hwloc_obj_type_t type)
     
    int hwloc_obj_type_is_cache (hwloc_obj_type_t type)
     
    int hwloc_obj_type_is_dcache (hwloc_obj_type_t type)
     
    int hwloc_obj_type_is_icache (hwloc_obj_type_t type)
     
    -

    Detailed Description

    -

    Each object type is either Normal (i.e. hwloc_obj_type_is_normal() returns 1), or Memory (i.e. hwloc_obj_type_is_memory() returns 1) or I/O (i.e. hwloc_obj_type_is_io() returns 1) or Misc (i.e. equal to HWLOC_OBJ_MISC). It cannot be of more than one of these kinds.

    -

    Function Documentation

    - -

    ◆ hwloc_obj_type_is_cache()

    - -
    -
    - - - - - - - - -
    int hwloc_obj_type_is_cache (hwloc_obj_type_t type)
    -
    - -

    Check whether an object type is a CPU Cache (Data, Unified or Instruction).

    -

    Memory-side caches are not CPU caches.

    -
    Returns
    1 if an object of type type is a Cache, 0 otherwise.
    - -
    -
    - -

    ◆ hwloc_obj_type_is_dcache()

    - -
    -
    - - - - - - - - -
    int hwloc_obj_type_is_dcache (hwloc_obj_type_t type)
    -
    - -

    Check whether an object type is a CPU Data or Unified Cache.

    -

    Memory-side caches are not CPU caches.

    -
    Returns
    1 if an object of type type is a CPU Data or Unified Cache, 0 otherwise.
    - -
    -
    - -

    ◆ hwloc_obj_type_is_icache()

    - -
    -
    - - - - - - - - -
    int hwloc_obj_type_is_icache (hwloc_obj_type_t type)
    -
    - -

    Check whether an object type is a CPU Instruction Cache,.

    -

    Memory-side caches are not CPU caches.

    -
    Returns
    1 if an object of type type is a CPU Instruction Cache, 0 otherwise.
    - -
    -
    - -

    ◆ hwloc_obj_type_is_io()

    - -
    -
    - - - - - - - - -
    int hwloc_obj_type_is_io (hwloc_obj_type_t type)
    -
    - -

    Check whether an object type is I/O.

    -

    I/O objects are objects attached to their parents in the I/O children list. This current includes Bridges, PCI and OS devices.

    -
    Returns
    1 if an object of type type is a I/O object, 0 otherwise.
    - -
    -
    - -

    ◆ hwloc_obj_type_is_memory()

    - -
    -
    - - - - - - - - -
    int hwloc_obj_type_is_memory (hwloc_obj_type_t type)
    -
    - -

    Check whether an object type is Memory.

    -

    Memory objects are objects attached to their parents in the Memory children list. This current includes NUMA nodes and Memory-side caches.

    -
    Returns
    1 if an object of type type is a Memory object, 0 otherwise.
    - -
    -
    - -

    ◆ hwloc_obj_type_is_normal()

    - -
    -
    - - - - - - - - -
    int hwloc_obj_type_is_normal (hwloc_obj_type_t type)
    -
    - -

    Check whether an object type is Normal.

    -

    Normal objects are objects of the main CPU hierarchy (Machine, Package, Core, PU, CPU caches, etc.), but they are not NUMA nodes, I/O devices or Misc objects.

    -

    They are attached to parent as Normal children, not as Memory, I/O or Misc children.

    -
    Returns
    1 if an object of type type is a Normal object, 0 otherwise.
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    Looking at Cache Objects
    -
    -
    - - - - - - - - -

    -Functions

    static int hwloc_get_cache_type_depth (hwloc_topology_t topology, unsigned cachelevel, hwloc_obj_cache_type_t cachetype)
     
    static hwloc_obj_t hwloc_get_cache_covering_cpuset (hwloc_topology_t topology, hwloc_const_cpuset_t set)
     
    static hwloc_obj_t hwloc_get_shared_cache_covering_obj (hwloc_topology_t topology, hwloc_obj_t obj)
     
    -

    Detailed Description

    -

    Function Documentation

    - -

    ◆ hwloc_get_cache_covering_cpuset()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_cache_covering_cpuset (hwloc_topology_t topology,
    hwloc_const_cpuset_t set 
    )
    -     		-inlinestatic
    -
    - -

    Get the first data (or unified) cache covering a cpuset set.

    -
    Returns
    a covering cache, or NULL if no cache matches.
    - -
    -
    - -

    ◆ hwloc_get_cache_type_depth()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_get_cache_type_depth (hwloc_topology_t topology,
    unsigned cachelevel,
    hwloc_obj_cache_type_t cachetype 
    )
    -     		-inlinestatic
    -
    - -

    Find the depth of cache objects matching cache level and type.

    -

    Return the depth of the topology level that contains cache objects whose attributes match cachelevel and cachetype.

    -

    This function is identical to calling hwloc_get_type_depth() with the corresponding type such as HWLOC_OBJ_L1ICACHE, except that it may also return a Unified cache when looking for an instruction cache.

    -
    Returns
    the depth of the unique matching unified cache level is returned if cachetype is HWLOC_OBJ_CACHE_UNIFIED.
    -
    -the depth of either a matching cache level or a unified cache level if cachetype is HWLOC_OBJ_CACHE_DATA or HWLOC_OBJ_CACHE_INSTRUCTION.
    -
    -the depth of the matching level if cachetype is -1 but only one level matches.
    -
    -HWLOC_TYPE_DEPTH_MULTIPLE if cachetype is -1 but multiple levels match.
    -
    -HWLOC_TYPE_DEPTH_UNKNOWN if no cache level matches.
    - -
    -
    - -

    ◆ hwloc_get_shared_cache_covering_obj()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_shared_cache_covering_obj (hwloc_topology_t topology,
    hwloc_obj_t obj 
    )
    -     		-inlinestatic
    -
    - -

    Get the first data (or unified) cache shared between an object and somebody else.

    -
    Returns
    a shared cache.
    -
    -NULL if no cache matches or if an invalid object is given (e.g. I/O object).
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    Finding objects, miscellaneous helpers
    -
    -
    - - - - - - - - - - - - - - - - -

    -Functions

    int hwloc_bitmap_singlify_per_core (hwloc_topology_t topology, hwloc_bitmap_t cpuset, unsigned which)
     
    static hwloc_obj_t hwloc_get_pu_obj_by_os_index (hwloc_topology_t topology, unsigned os_index)
     
    static hwloc_obj_t hwloc_get_numanode_obj_by_os_index (hwloc_topology_t topology, unsigned os_index)
     
    unsigned hwloc_get_closest_objs (hwloc_topology_t topology, hwloc_obj_t src, hwloc_obj_t *restrict objs, unsigned max)
     
    static hwloc_obj_t hwloc_get_obj_below_by_type (hwloc_topology_t topology, hwloc_obj_type_t type1, unsigned idx1, hwloc_obj_type_t type2, unsigned idx2)
     
    static hwloc_obj_t hwloc_get_obj_below_array_by_type (hwloc_topology_t topology, int nr, hwloc_obj_type_t *typev, unsigned *idxv)
     
    hwloc_obj_t hwloc_get_obj_with_same_locality (hwloc_topology_t topology, hwloc_obj_t src, hwloc_obj_type_t type, const char *subtype, const char *nameprefix, unsigned long flags)
     
    -

    Detailed Description

    -

    Be sure to see the figure in Terms and Definitions that shows a complete topology tree, including depths, child/sibling/cousin relationships, and an example of an asymmetric topology where one package has fewer caches than its peers.

    -

    Function Documentation

    - -

    ◆ hwloc_bitmap_singlify_per_core()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_singlify_per_core (hwloc_topology_t topology,
    hwloc_bitmap_t cpuset,
    unsigned which 
    )
    -
    - -

    Remove simultaneous multithreading PUs from a CPU set.

    -

    For each core in topology, if cpuset contains some PUs of that core, modify cpuset to only keep a single PU for that core.

    -

    which specifies which PU will be kept. PU are considered in physical index order. If 0, for each core, the function keeps the first PU that was originally set in cpuset.

    -

    If which is larger than the number of PUs in a core there were originally set in cpuset, no PU is kept for that core.

    -
    Returns
    0.
    -
    Note
    PUs that are not below a Core object are ignored (for instance if the topology does not contain any Core object). None of them is removed from cpuset.
    - -
    -
    - -

    ◆ hwloc_get_closest_objs()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    unsigned hwloc_get_closest_objs (hwloc_topology_t topology,
    hwloc_obj_t src,
    hwloc_obj_t *restrict objs,
    unsigned max 
    )
    -
    - -

    Do a depth-first traversal of the topology to find and sort.

    -

    all objects that are at the same depth than src. Report in objs up to max physically closest ones to src.

    -
    Returns
    the number of objects returned in objs.
    -
    -0 if src is an I/O object.
    -
    Note
    This function requires the src object to have a CPU set.
    - -
    -
    - -

    ◆ hwloc_get_numanode_obj_by_os_index()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_numanode_obj_by_os_index (hwloc_topology_t topology,
    unsigned os_index 
    )
    -     		-inlinestatic
    -
    - -

    Returns the object of type HWLOC_OBJ_NUMANODE with os_index.

    -

    This function is useful for converting a nodeset into the NUMA node objects it contains. When retrieving the current binding (e.g. with hwloc_get_membind() with HWLOC_MEMBIND_BYNODESET), one may iterate over the bits of the resulting nodeset with hwloc_bitmap_foreach_begin(), and find the corresponding NUMA nodes with this function.

    -
    Returns
    the NUMA node object, or NULL if none matches.
    - -
    -
    - -

    ◆ hwloc_get_obj_below_array_by_type()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_obj_below_array_by_type (hwloc_topology_t topology,
    int nr,
    hwloc_obj_type_t * typev,
    unsigned * idxv 
    )
    -     		-inlinestatic
    -
    - -

    Find an object below a chain of objects specified by types and indexes.

    -

    This is a generalized version of hwloc_get_obj_below_by_type().

    -

    Arrays typev and idxv must contain nr types and indexes.

    -

    Start from the top system object and walk the arrays typev and idxv. For each type and logical index couple in the arrays, look under the previously found object to find the index-th object of the given type. Indexes are specified within the parent, not withing the entire system.

    -

    For instance, if nr is 3, typev contains NODE, PACKAGE and CORE, and idxv contains 0, 1 and 2, return the third core object below the second package below the first NUMA node.

    -
    Returns
    a matching object if any, NULL otherwise.
    -
    Note
    This function requires all these objects and the root object to have a CPU set.
    - -
    -
    - -

    ◆ hwloc_get_obj_below_by_type()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_obj_below_by_type (hwloc_topology_t topology,
    hwloc_obj_type_t type1,
    unsigned idx1,
    hwloc_obj_type_t type2,
    unsigned idx2 
    )
    -     		-inlinestatic
    -
    - -

    Find an object below another object, both specified by types and indexes.

    -

    Start from the top system object and find object of type type1 and logical index idx1. Then look below this object and find another object of type type2 and logical index idx2. Indexes are specified within the parent, not withing the entire system.

    -

    For instance, if type1 is PACKAGE, idx1 is 2, type2 is CORE and idx2 is 3, return the fourth core object below the third package.

    -
    Returns
    a matching object if any, NULL otherwise.
    -
    Note
    This function requires these objects to have a CPU set.
    - -
    -
    - -

    ◆ hwloc_get_obj_with_same_locality()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    hwloc_obj_t hwloc_get_obj_with_same_locality (hwloc_topology_t topology,
    hwloc_obj_t src,
    hwloc_obj_type_t type,
    const char * subtype,
    const char * nameprefix,
    unsigned long flags 
    )
    -
    - -

    Return an object of a different type with same locality.

    -

    If the source object src is a normal or memory type, this function returns an object of type type with same CPU and node sets, either below or above in the hierarchy.

    -

    If the source object src is a PCI or an OS device within a PCI device, the function may either return that PCI device, or another OS device in the same PCI parent. This may for instance be useful for converting between OS devices such as "nvml0" or "rsmi1" used in distance structures into the the PCI device, or the CUDA or OpenCL OS device that correspond to the same physical card.

    -

    If not NULL, parameter subtype only select objects whose subtype attribute exists and is subtype (case-insensitively), for instance "OpenCL" or "CUDA".

    -

    If not NULL, parameter nameprefix only selects objects whose name attribute exists and starts with nameprefix (case-insensitively), for instance "rsmi" for matching "rsmi0".

    -

    If multiple objects match, the first one is returned.

    -

    This function will not walk the hierarchy across bridges since the PCI locality may become different. This function cannot also convert between normal/memory objects and I/O or Misc objects.

    -

    flags must be 0 for now.

    -
    Returns
    An object with identical locality, matching subtype and nameprefix if any.
    -
    -NULL if no matching object could be found, or if the source object and target type are incompatible, for instance if converting between CPU and I/O objects.
    - -
    -
    - -

    ◆ hwloc_get_pu_obj_by_os_index()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_pu_obj_by_os_index (hwloc_topology_t topology,
    unsigned os_index 
    )
    -     		-inlinestatic
    -
    - -

    Returns the object of type HWLOC_OBJ_PU with os_index.

    -

    This function is useful for converting a CPU set into the PU objects it contains. When retrieving the current binding (e.g. with hwloc_get_cpubind()), one may iterate over the bits of the resulting CPU set with hwloc_bitmap_foreach_begin(), and find the corresponding PUs with this function.

    -
    Returns
    the PU object, or NULL if none matches.
    - -
    -
    -
    - - - - - - - -
    -
    -Enumerations | -Functions
    -
    Distributing items over a topology
    -
    -
    - - - - -

    -Enumerations

    enum  hwloc_distrib_flags_e { HWLOC_DISTRIB_FLAG_REVERSE - }
     
    - - - -

    -Functions

    static int hwloc_distrib (hwloc_topology_t topology, hwloc_obj_t *roots, unsigned n_roots, hwloc_cpuset_t *set, unsigned n, int until, unsigned long flags)
     
    -

    Detailed Description

    -

    Enumeration Type Documentation

    - -

    ◆ hwloc_distrib_flags_e

    - -
    -
    - - - - -
    enum hwloc_distrib_flags_e
    -
    - -

    Flags to be given to hwloc_distrib().

    - - -
    Enumerator
    HWLOC_DISTRIB_FLAG_REVERSE 

    Distrib in reverse order, starting from the last objects.

    -
    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_distrib()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_distrib (hwloc_topology_t topology,
    hwloc_obj_t * roots,
    unsigned n_roots,
    hwloc_cpuset_t * set,
    unsigned n,
    int until,
    unsigned long flags 
    )
    -     		-inlinestatic
    -
    - -

    Distribute n items over the topology under roots.

    -

    Array set will be filled with n cpusets recursively distributed linearly over the topology under objects roots, down to depth until (which can be INT_MAX to distribute down to the finest level).

    -

    n_roots is usually 1 and roots only contains the topology root object so as to distribute over the entire topology.

    -

    This is typically useful when an application wants to distribute n threads over a machine, giving each of them as much private cache as possible and keeping them locally in number order.

    -

    The caller may typically want to also call hwloc_bitmap_singlify() before binding a thread so that it does not move at all.

    -

    flags should be 0 or a OR'ed set of hwloc_distrib_flags_e.

    -
    Returns
    0 on success, -1 on error.
    -
    Note
    This function requires the roots objects to have a CPU set.
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    CPU and node sets of entire topologies
    -
    -
    - - - - - - - - - - - - - - -

    -Functions

    hwloc_const_cpuset_t hwloc_topology_get_complete_cpuset (hwloc_topology_t topology)
     
    hwloc_const_cpuset_t hwloc_topology_get_topology_cpuset (hwloc_topology_t topology)
     
    hwloc_const_cpuset_t hwloc_topology_get_allowed_cpuset (hwloc_topology_t topology)
     
    hwloc_const_nodeset_t hwloc_topology_get_complete_nodeset (hwloc_topology_t topology)
     
    hwloc_const_nodeset_t hwloc_topology_get_topology_nodeset (hwloc_topology_t topology)
     
    hwloc_const_nodeset_t hwloc_topology_get_allowed_nodeset (hwloc_topology_t topology)
     
    -

    Detailed Description

    -

    Function Documentation

    - -

    ◆ hwloc_topology_get_allowed_cpuset()

    - -
    -
    - - - - - - - - -
    hwloc_const_cpuset_t hwloc_topology_get_allowed_cpuset (hwloc_topology_t topology)
    -
    - -

    Get allowed CPU set.

    -
    Returns
    the CPU set of allowed processors of the system.
    -
    Note
    This function cannot return NULL.
    -
    -If the topology flag HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED was not set, this is identical to hwloc_topology_get_topology_cpuset(), which means all PUs are allowed.
    -
    -If HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED was set, applying hwloc_bitmap_intersects() on the result of this function and on an object cpuset checks whether there are allowed PUs inside that object. Applying hwloc_bitmap_and() returns the list of these allowed PUs.
    -
    -The returned cpuset is not newly allocated and should thus not be changed or freed, hwloc_bitmap_dup() must be used to obtain a local copy.
    - -
    -
    - -

    ◆ hwloc_topology_get_allowed_nodeset()

    - -
    -
    - - - - - - - - -
    hwloc_const_nodeset_t hwloc_topology_get_allowed_nodeset (hwloc_topology_t topology)
    -
    - -

    Get allowed node set.

    -
    Returns
    the node set of allowed memory of the system.
    -
    Note
    This function cannot return NULL.
    -
    -If the topology flag HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED was not set, this is identical to hwloc_topology_get_topology_nodeset(), which means all NUMA nodes are allowed.
    -
    -If HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED was set, applying hwloc_bitmap_intersects() on the result of this function and on an object nodeset checks whether there are allowed NUMA nodes inside that object. Applying hwloc_bitmap_and() returns the list of these allowed NUMA nodes.
    -
    -The returned nodeset is not newly allocated and should thus not be changed or freed, hwloc_bitmap_dup() must be used to obtain a local copy.
    - -
    -
    - -

    ◆ hwloc_topology_get_complete_cpuset()

    - -
    -
    - - - - - - - - -
    hwloc_const_cpuset_t hwloc_topology_get_complete_cpuset (hwloc_topology_t topology)
    -
    - -

    Get complete CPU set.

    -
    Returns
    the complete CPU set of processors of the system.
    -
    Note
    This function cannot return NULL.
    -
    -The returned cpuset is not newly allocated and should thus not be changed or freed; hwloc_bitmap_dup() must be used to obtain a local copy.
    -
    -This is equivalent to retrieving the root object complete CPU-set.
    - -
    -
    - -

    ◆ hwloc_topology_get_complete_nodeset()

    - -
    -
    - - - - - - - - -
    hwloc_const_nodeset_t hwloc_topology_get_complete_nodeset (hwloc_topology_t topology)
    -
    - -

    Get complete node set.

    -
    Returns
    the complete node set of memory of the system.
    -
    Note
    This function cannot return NULL.
    -
    -The returned nodeset is not newly allocated and should thus not be changed or freed; hwloc_bitmap_dup() must be used to obtain a local copy.
    -
    -This is equivalent to retrieving the root object complete nodeset.
    - -
    -
    - -

    ◆ hwloc_topology_get_topology_cpuset()

    - -
    -
    - - - - - - - - -
    hwloc_const_cpuset_t hwloc_topology_get_topology_cpuset (hwloc_topology_t topology)
    -
    - -

    Get topology CPU set.

    -
    Returns
    the CPU set of processors of the system for which hwloc provides topology information. This is equivalent to the cpuset of the system object.
    -
    Note
    This function cannot return NULL.
    -
    -The returned cpuset is not newly allocated and should thus not be changed or freed; hwloc_bitmap_dup() must be used to obtain a local copy.
    -
    -This is equivalent to retrieving the root object CPU-set.
    - -
    -
    - -

    ◆ hwloc_topology_get_topology_nodeset()

    - -
    -
    - - - - - - - - -
    hwloc_const_nodeset_t hwloc_topology_get_topology_nodeset (hwloc_topology_t topology)
    -
    - -

    Get topology node set.

    -
    Returns
    the node set of memory of the system for which hwloc provides topology information. This is equivalent to the nodeset of the system object.
    -
    Note
    This function cannot return NULL.
    -
    -The returned nodeset is not newly allocated and should thus not be changed or freed; hwloc_bitmap_dup() must be used to obtain a local copy.
    -
    -This is equivalent to retrieving the root object nodeset.
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    Converting between CPU sets and node sets
    -
    -
    - - - - - - -

    -Functions

    static int hwloc_cpuset_to_nodeset (hwloc_topology_t topology, hwloc_const_cpuset_t _cpuset, hwloc_nodeset_t nodeset)
     
    static int hwloc_cpuset_from_nodeset (hwloc_topology_t topology, hwloc_cpuset_t _cpuset, hwloc_const_nodeset_t nodeset)
     
    -

    Detailed Description

    -

    Function Documentation

    - -

    ◆ hwloc_cpuset_from_nodeset()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_cpuset_from_nodeset (hwloc_topology_t topology,
    hwloc_cpuset_t _cpuset,
    hwloc_const_nodeset_t nodeset 
    )
    -     		-inlinestatic
    -
    - -

    Convert a NUMA node set into a CPU set.

    -

    For each NUMA node included in the input nodeset, set the corresponding local PUs in the output _cpuset.

    -

    If some CPUs have no local NUMA nodes, this function never sets their indexes in the output CPU set, even if a full node set is given in input.

    -

    Hence the entire topology node set is converted into the set of all CPUs that have some local NUMA nodes.

    -
    Returns
    0 on success.
    -
    --1 with errno set to ENOMEM on internal reallocation failure.
    - -
    -
    - -

    ◆ hwloc_cpuset_to_nodeset()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_cpuset_to_nodeset (hwloc_topology_t topology,
    hwloc_const_cpuset_t _cpuset,
    hwloc_nodeset_t nodeset 
    )
    -     		-inlinestatic
    -
    - -

    Convert a CPU set into a NUMA node set.

    -

    For each PU included in the input _cpuset, set the corresponding local NUMA node(s) in the output nodeset.

    -

    If some NUMA nodes have no CPUs at all, this function never sets their indexes in the output node set, even if a full CPU set is given in input.

    -

    Hence the entire topology CPU set is converted into the set of all nodes that have some local CPUs.

    -
    Returns
    0 on success.
    -
    --1 with errno set to ENOMEM on internal reallocation failure.
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    Finding I/O objects
    -
    -
    - - - - - - - - - - - - - - - - -

    -Functions

    static hwloc_obj_t hwloc_get_non_io_ancestor_obj (hwloc_topology_t topology, hwloc_obj_t ioobj)
     
    static hwloc_obj_t hwloc_get_next_pcidev (hwloc_topology_t topology, hwloc_obj_t prev)
     
    static hwloc_obj_t hwloc_get_pcidev_by_busid (hwloc_topology_t topology, unsigned domain, unsigned bus, unsigned dev, unsigned func)
     
    static hwloc_obj_t hwloc_get_pcidev_by_busidstring (hwloc_topology_t topology, const char *busid)
     
    static hwloc_obj_t hwloc_get_next_osdev (hwloc_topology_t topology, hwloc_obj_t prev)
     
    static hwloc_obj_t hwloc_get_next_bridge (hwloc_topology_t topology, hwloc_obj_t prev)
     
    static int hwloc_bridge_covers_pcibus (hwloc_obj_t bridge, unsigned domain, unsigned bus)
     
    -

    Detailed Description

    -

    Function Documentation

    - -

    ◆ hwloc_bridge_covers_pcibus()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_bridge_covers_pcibus (hwloc_obj_t bridge,
    unsigned domain,
    unsigned bus 
    )
    -     		-inlinestatic
    -
    - -
    -
    - -

    ◆ hwloc_get_next_bridge()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_next_bridge (hwloc_topology_t topology,
    hwloc_obj_t prev 
    )
    -     		-inlinestatic
    -
    - -

    Get the next bridge in the system.

    -
    Returns
    the first bridge if prev is NULL.
    -
    -the next bridge if prev is not NULL.
    -
    -NULL if there is no next bridge.
    - -
    -
    - -

    ◆ hwloc_get_next_osdev()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_next_osdev (hwloc_topology_t topology,
    hwloc_obj_t prev 
    )
    -     		-inlinestatic
    -
    - -

    Get the next OS device in the system.

    -
    Returns
    the first OS device if prev is NULL.
    -
    -the next OS device if prev is not NULL.
    -
    -NULL if there is no next OS device.
    - -
    -
    - -

    ◆ hwloc_get_next_pcidev()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_next_pcidev (hwloc_topology_t topology,
    hwloc_obj_t prev 
    )
    -     		-inlinestatic
    -
    - -

    Get the next PCI device in the system.

    -
    Returns
    the first PCI device if prev is NULL.
    -
    -the next PCI device if prev is not NULL.
    -
    -NULL if there is no next PCI device.
    - -
    -
    - -

    ◆ hwloc_get_non_io_ancestor_obj()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_non_io_ancestor_obj (hwloc_topology_t topology,
    hwloc_obj_t ioobj 
    )
    -     		-inlinestatic
    -
    - -

    Get the first non-I/O ancestor object.

    -

    Given the I/O object ioobj, find the smallest non-I/O ancestor object. This object (normal or memory) may then be used for binding because it has non-NULL CPU and node sets and because its locality is the same as ioobj.

    -
    Returns
    a non-I/O object.
    -
    Note
    This function cannot return NULL.
    -
    -The resulting object is usually a normal object but it could also be a memory object (e.g. NUMA node) in future platforms if I/O objects ever get attached to memory instead of CPUs.
    - -
    -
    - -

    ◆ hwloc_get_pcidev_by_busid()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_pcidev_by_busid (hwloc_topology_t topology,
    unsigned domain,
    unsigned bus,
    unsigned dev,
    unsigned func 
    )
    -     		-inlinestatic
    -
    - -

    Find the PCI device object matching the PCI bus id given domain, bus device and function PCI bus id.

    -
    Returns
    a matching PCI device object if any, NULL otherwise.
    - -
    -
    - -

    ◆ hwloc_get_pcidev_by_busidstring()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_get_pcidev_by_busidstring (hwloc_topology_t topology,
    const char * busid 
    )
    -     		-inlinestatic
    -
    - -

    Find the PCI device object matching the PCI bus id given as a string xxxx:yy:zz.t or yy:zz.t.

    -
    Returns
    a matching PCI device object if any, NULL otherwise.
    - -
    -
    -
    - - - - - - - -
    -
    -Macros | -Typedefs | -Functions
    -
    The bitmap API
    -
    -
    - - - - - - -

    -Macros

    #define hwloc_bitmap_foreach_begin(id, bitmap)
     
    #define hwloc_bitmap_foreach_end()
     
    - - - - - -

    -Typedefs

    typedef struct hwloc_bitmap_s * hwloc_bitmap_t
     
    typedef const struct hwloc_bitmap_s * hwloc_const_bitmap_t
     
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

    -Functions

    hwloc_bitmap_t hwloc_bitmap_alloc (void)
     
    hwloc_bitmap_t hwloc_bitmap_alloc_full (void)
     
    void hwloc_bitmap_free (hwloc_bitmap_t bitmap)
     
    hwloc_bitmap_t hwloc_bitmap_dup (hwloc_const_bitmap_t bitmap)
     
    int hwloc_bitmap_copy (hwloc_bitmap_t dst, hwloc_const_bitmap_t src)
     
    int hwloc_bitmap_snprintf (char *restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap)
     
    int hwloc_bitmap_asprintf (char **strp, hwloc_const_bitmap_t bitmap)
     
    int hwloc_bitmap_sscanf (hwloc_bitmap_t bitmap, const char *restrict string)
     
    int hwloc_bitmap_list_snprintf (char *restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap)
     
    int hwloc_bitmap_list_asprintf (char **strp, hwloc_const_bitmap_t bitmap)
     
    int hwloc_bitmap_list_sscanf (hwloc_bitmap_t bitmap, const char *restrict string)
     
    int hwloc_bitmap_taskset_snprintf (char *restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap)
     
    int hwloc_bitmap_taskset_asprintf (char **strp, hwloc_const_bitmap_t bitmap)
     
    int hwloc_bitmap_taskset_sscanf (hwloc_bitmap_t bitmap, const char *restrict string)
     
    void hwloc_bitmap_zero (hwloc_bitmap_t bitmap)
     
    void hwloc_bitmap_fill (hwloc_bitmap_t bitmap)
     
    int hwloc_bitmap_only (hwloc_bitmap_t bitmap, unsigned id)
     
    int hwloc_bitmap_allbut (hwloc_bitmap_t bitmap, unsigned id)
     
    int hwloc_bitmap_from_ulong (hwloc_bitmap_t bitmap, unsigned long mask)
     
    int hwloc_bitmap_from_ith_ulong (hwloc_bitmap_t bitmap, unsigned i, unsigned long mask)
     
    int hwloc_bitmap_from_ulongs (hwloc_bitmap_t bitmap, unsigned nr, const unsigned long *masks)
     
    int hwloc_bitmap_set (hwloc_bitmap_t bitmap, unsigned id)
     
    int hwloc_bitmap_set_range (hwloc_bitmap_t bitmap, unsigned begin, int end)
     
    int hwloc_bitmap_set_ith_ulong (hwloc_bitmap_t bitmap, unsigned i, unsigned long mask)
     
    int hwloc_bitmap_clr (hwloc_bitmap_t bitmap, unsigned id)
     
    int hwloc_bitmap_clr_range (hwloc_bitmap_t bitmap, unsigned begin, int end)
     
    int hwloc_bitmap_singlify (hwloc_bitmap_t bitmap)
     
    unsigned long hwloc_bitmap_to_ulong (hwloc_const_bitmap_t bitmap)
     
    unsigned long hwloc_bitmap_to_ith_ulong (hwloc_const_bitmap_t bitmap, unsigned i)
     
    int hwloc_bitmap_to_ulongs (hwloc_const_bitmap_t bitmap, unsigned nr, unsigned long *masks)
     
    int hwloc_bitmap_nr_ulongs (hwloc_const_bitmap_t bitmap)
     
    int hwloc_bitmap_isset (hwloc_const_bitmap_t bitmap, unsigned id)
     
    int hwloc_bitmap_iszero (hwloc_const_bitmap_t bitmap)
     
    int hwloc_bitmap_isfull (hwloc_const_bitmap_t bitmap)
     
    int hwloc_bitmap_first (hwloc_const_bitmap_t bitmap)
     
    int hwloc_bitmap_next (hwloc_const_bitmap_t bitmap, int prev)
     
    int hwloc_bitmap_last (hwloc_const_bitmap_t bitmap)
     
    int hwloc_bitmap_weight (hwloc_const_bitmap_t bitmap)
     
    int hwloc_bitmap_first_unset (hwloc_const_bitmap_t bitmap)
     
    int hwloc_bitmap_next_unset (hwloc_const_bitmap_t bitmap, int prev)
     
    int hwloc_bitmap_last_unset (hwloc_const_bitmap_t bitmap)
     
    int hwloc_bitmap_or (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
     
    int hwloc_bitmap_and (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
     
    int hwloc_bitmap_andnot (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
     
    int hwloc_bitmap_xor (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
     
    int hwloc_bitmap_not (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap)
     
    int hwloc_bitmap_intersects (hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
     
    int hwloc_bitmap_isincluded (hwloc_const_bitmap_t sub_bitmap, hwloc_const_bitmap_t super_bitmap)
     
    int hwloc_bitmap_isequal (hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
     
    int hwloc_bitmap_compare_first (hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
     
    int hwloc_bitmap_compare (hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
     
    -

    Detailed Description

    -

    The hwloc_bitmap_t type represents a set of integers (positive or null). A bitmap may be of infinite size (all bits are set after some point). A bitmap may even be full if all bits are set.

    -

    Bitmaps are used by hwloc for sets of OS processors (which may actually be hardware threads) as by hwloc_cpuset_t (a typedef for hwloc_bitmap_t), or sets of NUMA memory nodes as hwloc_nodeset_t (also a typedef for hwloc_bitmap_t). Those are used for cpuset and nodeset fields in the hwloc_obj structure, see Object Sets (hwloc_cpuset_t and hwloc_nodeset_t).

    -

    Both CPU and node sets are always indexed by OS physical number. However users should usually not build CPU and node sets manually (e.g. with hwloc_bitmap_set()). One should rather use existing object sets and combine them with hwloc_bitmap_or(), etc. For instance, binding the current thread on a pair of cores may be performed with:

    hwloc_obj_t core1 = ... , core2 = ... ;
    -
    hwloc_bitmap_t set = hwloc_bitmap_alloc();
    -
    hwloc_bitmap_or(set, core1->cpuset, core2->cpuset);
    -
    hwloc_set_cpubind(topology, set, HWLOC_CPUBIND_THREAD);
    -
    hwloc_bitmap_free(set);
    -
    hwloc_set_cpubind
    int hwloc_set_cpubind(hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags)
    Bind current process or thread on CPUs given in physical bitmap set.
    -
    HWLOC_CPUBIND_THREAD
    @ HWLOC_CPUBIND_THREAD
    Bind current thread of current process.
    Definition: hwloc.h:1214
    -
    hwloc_bitmap_or
    int hwloc_bitmap_or(hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
    Or bitmaps bitmap1 and bitmap2 and store the result in bitmap res.
    -
    hwloc_bitmap_free
    void hwloc_bitmap_free(hwloc_bitmap_t bitmap)
    Free bitmap bitmap.
    -
    hwloc_bitmap_t
    struct hwloc_bitmap_s * hwloc_bitmap_t
    Set of bits represented as an opaque pointer to an internal bitmap.
    Definition: bitmap.h:69
    -
    hwloc_bitmap_alloc
    hwloc_bitmap_t hwloc_bitmap_alloc(void)
    Allocate a new empty bitmap.
    -
    hwloc_obj
    Structure of a topology object.
    Definition: hwloc.h:420
    -
    hwloc_obj::cpuset
    hwloc_cpuset_t cpuset
    CPUs covered by this object.
    Definition: hwloc.h:536
    -
    Note
    Most functions below return 0 on success and -1 on error. The usual error case would be an internal failure to realloc/extend the storage of the bitmap (errno would be set to ENOMEM). See also Error reporting in the API.
    -
    -Several examples of using the bitmap API are available under the doc/examples/ directory in the source tree. Regression tests such as tests/hwloc/hwloc_bitmap*.c also make intensive use of this API.
    -

    Macro Definition Documentation

    - -

    ◆ hwloc_bitmap_foreach_begin

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    #define hwloc_bitmap_foreach_begin( id,
     bitmap 
    )
    -
    - -

    Loop macro iterating on bitmap bitmap.

    -

    The loop must start with hwloc_bitmap_foreach_begin() and end with hwloc_bitmap_foreach_end() followed by a terminating ';'.

    -

    id is the loop variable; it should be an unsigned int. The first iteration will set id to the lowest index in the bitmap. Successive iterations will iterate through, in order, all remaining indexes set in the bitmap. To be specific: each iteration will return a value for id such that hwloc_bitmap_isset(bitmap, id) is true.

    -

    The assert prevents the loop from being infinite if the bitmap is infinitely set.

    - -
    -
    - -

    ◆ hwloc_bitmap_foreach_end

    - -
    -
    - - - - - - - -
    #define hwloc_bitmap_foreach_end()
    -
    - -

    End of loop macro iterating on a bitmap.

    -

    Needs a terminating ';'.

    -
    See also
    hwloc_bitmap_foreach_begin()
    - -
    -
    -

    Typedef Documentation

    - -

    ◆ hwloc_bitmap_t

    - -
    -
    - - - - -
    typedef struct hwloc_bitmap_s* hwloc_bitmap_t
    -
    - -

    Set of bits represented as an opaque pointer to an internal bitmap.

    - -
    -
    - -

    ◆ hwloc_const_bitmap_t

    - -
    -
    - - - - -
    typedef const struct hwloc_bitmap_s* hwloc_const_bitmap_t
    -
    - -

    a non-modifiable hwloc_bitmap_t

    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_bitmap_allbut()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_allbut (hwloc_bitmap_t bitmap,
    unsigned id 
    )
    -
    - -

    Fill the bitmap and clear the index id.

    - -
    -
    - -

    ◆ hwloc_bitmap_alloc()

    - -
    -
    - - - - - - - - -
    hwloc_bitmap_t hwloc_bitmap_alloc (void )
    -
    - -

    Allocate a new empty bitmap.

    -
    Returns
    A valid bitmap or NULL.
    -

    The bitmap should be freed by a corresponding call to hwloc_bitmap_free().

    - -
    -
    - -

    ◆ hwloc_bitmap_alloc_full()

    - -
    -
    - - - - - - - - -
    hwloc_bitmap_t hwloc_bitmap_alloc_full (void )
    -
    - -

    Allocate a new full bitmap.

    -
    Returns
    A valid bitmap or NULL.
    -

    The bitmap should be freed by a corresponding call to hwloc_bitmap_free().

    - -
    -
    - -

    ◆ hwloc_bitmap_and()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_and (hwloc_bitmap_t res,
    hwloc_const_bitmap_t bitmap1,
    hwloc_const_bitmap_t bitmap2 
    )
    -
    - -

    And bitmaps bitmap1 and bitmap2 and store the result in bitmap res.

    -

    res can be the same as bitmap1 or bitmap2

    - -
    -
    - -

    ◆ hwloc_bitmap_andnot()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_andnot (hwloc_bitmap_t res,
    hwloc_const_bitmap_t bitmap1,
    hwloc_const_bitmap_t bitmap2 
    )
    -
    - -

    And bitmap bitmap1 and the negation of bitmap2 and store the result in bitmap res.

    -

    res can be the same as bitmap1 or bitmap2

    - -
    -
    - -

    ◆ hwloc_bitmap_asprintf()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_asprintf (char ** strp,
    hwloc_const_bitmap_t bitmap 
    )
    -
    - -

    Stringify a bitmap into a newly allocated string.

    -
    Returns
    0 on success, -1 on error.
    - -
    -
    - -

    ◆ hwloc_bitmap_clr()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_clr (hwloc_bitmap_t bitmap,
    unsigned id 
    )
    -
    - -

    Remove index id from bitmap bitmap.

    - -
    -
    - -

    ◆ hwloc_bitmap_clr_range()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_clr_range (hwloc_bitmap_t bitmap,
    unsigned begin,
    int end 
    )
    -
    - -

    Remove indexes from begin to end in bitmap bitmap.

    -

    If end is -1, the range is infinite.

    - -
    -
    - -

    ◆ hwloc_bitmap_compare()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_compare (hwloc_const_bitmap_t bitmap1,
    hwloc_const_bitmap_t bitmap2 
    )
    -
    - -

    Compare bitmaps bitmap1 and bitmap2 in lexicographic order.

    -

    Lexicographic comparison of bitmaps, starting for their highest indexes. Compare last indexes first, then second, etc. The empty bitmap is considered lower than anything.

    -
    Returns
    -1 if bitmap1 is considered smaller than bitmap2.
    -
    -1 if bitmap1 is considered larger than bitmap2.
    -
    -0 if bitmaps are equal (contrary to hwloc_bitmap_compare_first()).
    -

    For instance comparing binary bitmaps 0011 and 0110 returns -1 (hence 0011 is considered smaller than 0110). Comparing 00101 and 01010 returns -1 too.

    -
    Note
    This is different from the non-existing hwloc_bitmap_compare_last() which would only compare the highest index of each bitmap.
    - -
    -
    - -

    ◆ hwloc_bitmap_compare_first()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_compare_first (hwloc_const_bitmap_t bitmap1,
    hwloc_const_bitmap_t bitmap2 
    )
    -
    - -

    Compare bitmaps bitmap1 and bitmap2 using their lowest index.

    -

    A bitmap is considered smaller if its least significant bit is smaller. The empty bitmap is considered higher than anything (because its least significant bit does not exist).

    -
    Returns
    -1 if bitmap1 is considered smaller than bitmap2.
    -
    -1 if bitmap1 is considered larger than bitmap2.
    -

    For instance comparing binary bitmaps 0011 and 0110 returns -1 (hence 0011 is considered smaller than 0110) because least significant bit of 0011 (0001) is smaller than least significant bit of 0110 (0010). Comparing 01001 and 00110 would also return -1 for the same reason.

    -
    Returns
    0 if bitmaps are considered equal, even if they are not strictly equal. They just need to have the same least significant bit. For instance, comparing binary bitmaps 0010 and 0110 returns 0 because they have the same least significant bit.
    - -
    -
    - -

    ◆ hwloc_bitmap_copy()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_copy (hwloc_bitmap_t dst,
    hwloc_const_bitmap_t src 
    )
    -
    - -

    Copy the contents of bitmap src into the already allocated bitmap dst.

    - -
    -
    - -

    ◆ hwloc_bitmap_dup()

    - -
    -
    - - - - - - - - -
    hwloc_bitmap_t hwloc_bitmap_dup (hwloc_const_bitmap_t bitmap)
    -
    - -

    Duplicate bitmap bitmap by allocating a new bitmap and copying bitmap contents.

    -

    If bitmap is NULL, NULL is returned.

    - -
    -
    - -

    ◆ hwloc_bitmap_fill()

    - -
    -
    - - - - - - - - -
    void hwloc_bitmap_fill (hwloc_bitmap_t bitmap)
    -
    - -

    Fill bitmap bitmap with all possible indexes (even if those objects don't exist or are otherwise unavailable)

    - -
    -
    - -

    ◆ hwloc_bitmap_first()

    - -
    -
    - - - - - - - - -
    int hwloc_bitmap_first (hwloc_const_bitmap_t bitmap)
    -
    - -

    Compute the first index (least significant bit) in bitmap bitmap.

    -
    Returns
    the first index set in bitmap.
    -
    --1 if bitmap is empty.
    - -
    -
    - -

    ◆ hwloc_bitmap_first_unset()

    - -
    -
    - - - - - - - - -
    int hwloc_bitmap_first_unset (hwloc_const_bitmap_t bitmap)
    -
    - -

    Compute the first unset index (least significant bit) in bitmap bitmap.

    -
    Returns
    the first unset index in bitmap.
    -
    --1 if bitmap is full.
    - -
    -
    - -

    ◆ hwloc_bitmap_free()

    - -
    -
    - - - - - - - - -
    void hwloc_bitmap_free (hwloc_bitmap_t bitmap)
    -
    - -

    Free bitmap bitmap.

    -

    If bitmap is NULL, no operation is performed.

    - -
    -
    - -

    ◆ hwloc_bitmap_from_ith_ulong()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_from_ith_ulong (hwloc_bitmap_t bitmap,
    unsigned i,
    unsigned long mask 
    )
    -
    - -

    Setup bitmap bitmap from unsigned long mask used as i -th subset.

    - -
    -
    - -

    ◆ hwloc_bitmap_from_ulong()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_from_ulong (hwloc_bitmap_t bitmap,
    unsigned long mask 
    )
    -
    - -

    Setup bitmap bitmap from unsigned long mask.

    - -
    -
    - -

    ◆ hwloc_bitmap_from_ulongs()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_from_ulongs (hwloc_bitmap_t bitmap,
    unsigned nr,
    const unsigned long * masks 
    )
    -
    - -

    Setup bitmap bitmap from unsigned longs masks used as first nr subsets.

    - -
    -
    - -

    ◆ hwloc_bitmap_intersects()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_intersects (hwloc_const_bitmap_t bitmap1,
    hwloc_const_bitmap_t bitmap2 
    )
    -
    - -

    Test whether bitmaps bitmap1 and bitmap2 intersects.

    -
    Returns
    1 if bitmaps intersect, 0 otherwise.
    - -
    -
    - -

    ◆ hwloc_bitmap_isequal()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_isequal (hwloc_const_bitmap_t bitmap1,
    hwloc_const_bitmap_t bitmap2 
    )
    -
    - -

    Test whether bitmap bitmap1 is equal to bitmap bitmap2.

    -
    Returns
    1 if bitmaps are equal, 0 otherwise.
    - -
    -
    - -

    ◆ hwloc_bitmap_isfull()

    - -
    -
    - - - - - - - - -
    int hwloc_bitmap_isfull (hwloc_const_bitmap_t bitmap)
    -
    - -

    Test whether bitmap bitmap is completely full.

    -
    Returns
    1 if bitmap is full, 0 otherwise.
    -
    Note
    A full bitmap is always infinitely set.
    - -
    -
    - -

    ◆ hwloc_bitmap_isincluded()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_isincluded (hwloc_const_bitmap_t sub_bitmap,
    hwloc_const_bitmap_t super_bitmap 
    )
    -
    - -

    Test whether bitmap sub_bitmap is part of bitmap super_bitmap.

    -
    Returns
    1 if sub_bitmap is included in super_bitmap, 0 otherwise.
    -
    Note
    The empty bitmap is considered included in any other bitmap.
    - -
    -
    - -

    ◆ hwloc_bitmap_isset()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_isset (hwloc_const_bitmap_t bitmap,
    unsigned id 
    )
    -
    - -

    Test whether index id is part of bitmap bitmap.

    -
    Returns
    1 if the bit at index id is set in bitmap bitmap, 0 otherwise.
    - -
    -
    - -

    ◆ hwloc_bitmap_iszero()

    - -
    -
    - - - - - - - - -
    int hwloc_bitmap_iszero (hwloc_const_bitmap_t bitmap)
    -
    - -

    Test whether bitmap bitmap is empty.

    -
    Returns
    1 if bitmap is empty, 0 otherwise.
    - -
    -
    - -

    ◆ hwloc_bitmap_last()

    - -
    -
    - - - - - - - - -
    int hwloc_bitmap_last (hwloc_const_bitmap_t bitmap)
    -
    - -

    Compute the last index (most significant bit) in bitmap bitmap.

    -
    Returns
    the last index set in bitmap.
    -
    --1 if bitmap is empty, or if bitmap is infinitely set.
    - -
    -
    - -

    ◆ hwloc_bitmap_last_unset()

    - -
    -
    - - - - - - - - -
    int hwloc_bitmap_last_unset (hwloc_const_bitmap_t bitmap)
    -
    - -

    Compute the last unset index (most significant bit) in bitmap bitmap.

    -
    Returns
    the last index unset in bitmap.
    -
    --1 if bitmap is full, or if bitmap is not infinitely set.
    - -
    -
    - -

    ◆ hwloc_bitmap_list_asprintf()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_list_asprintf (char ** strp,
    hwloc_const_bitmap_t bitmap 
    )
    -
    - -

    Stringify a bitmap into a newly allocated list string.

    -
    Returns
    0 on success, -1 on error.
    - -
    -
    - -

    ◆ hwloc_bitmap_list_snprintf()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_list_snprintf (char *restrict buf,
    size_t buflen,
    hwloc_const_bitmap_t bitmap 
    )
    -
    - -

    Stringify a bitmap in the list format.

    -

    Lists are comma-separated indexes or ranges. Ranges are dash separated indexes. The last range may not have an ending indexes if the bitmap is infinitely set.

    -

    Up to buflen characters may be written in buffer buf.

    -

    If buflen is 0, buf may safely be NULL.

    -
    Returns
    the number of characters that were actually written if not truncating, or that would have been written (not including the ending \0).
    - -
    -
    - -

    ◆ hwloc_bitmap_list_sscanf()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_list_sscanf (hwloc_bitmap_t bitmap,
    const char *restrict string 
    )
    -
    - -

    Parse a list string and stores it in bitmap bitmap.

    -
    Returns
    0 on success, -1 on error.
    - -
    -
    - -

    ◆ hwloc_bitmap_next()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_next (hwloc_const_bitmap_t bitmap,
    int prev 
    )
    -
    - -

    Compute the next index in bitmap bitmap which is after index prev.

    -
    Returns
    the first index set in bitmap if prev is -1.
    -
    -the next index set in bitmap if prev is not -1.
    -
    --1 if no index with higher index is set in bitmap.
    - -
    -
    - -

    ◆ hwloc_bitmap_next_unset()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_next_unset (hwloc_const_bitmap_t bitmap,
    int prev 
    )
    -
    - -

    Compute the next unset index in bitmap bitmap which is after index prev.

    -
    Returns
    the first index unset in bitmap if prev is -1.
    -
    -the next index unset in bitmap if prev is not -1.
    -
    --1 if no index with higher index is unset in bitmap.
    - -
    -
    - -

    ◆ hwloc_bitmap_not()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_not (hwloc_bitmap_t res,
    hwloc_const_bitmap_t bitmap 
    )
    -
    - -

    Negate bitmap bitmap and store the result in bitmap res.

    -

    res can be the same as bitmap

    - -
    -
    - -

    ◆ hwloc_bitmap_nr_ulongs()

    - -
    -
    - - - - - - - - -
    int hwloc_bitmap_nr_ulongs (hwloc_const_bitmap_t bitmap)
    -
    - -

    Return the number of unsigned longs required for storing bitmap bitmap entirely.

    -

    This is the number of contiguous unsigned longs from the very first bit of the bitmap (even if unset) up to the last set bit. This is useful for knowing the nr parameter to pass to hwloc_bitmap_to_ulongs() (or which calls to hwloc_bitmap_to_ith_ulong() are needed) to entirely convert a bitmap into multiple unsigned longs.

    -

    When called on the output of hwloc_topology_get_topology_cpuset(), the returned number is large enough for all cpusets of the topology.

    -
    Returns
    the number of unsigned longs required.
    -
    --1 if bitmap is infinite.
    - -
    -
    - -

    ◆ hwloc_bitmap_only()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_only (hwloc_bitmap_t bitmap,
    unsigned id 
    )
    -
    - -

    Empty the bitmap bitmap and add bit id.

    - -
    -
    - -

    ◆ hwloc_bitmap_or()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_or (hwloc_bitmap_t res,
    hwloc_const_bitmap_t bitmap1,
    hwloc_const_bitmap_t bitmap2 
    )
    -
    - -

    Or bitmaps bitmap1 and bitmap2 and store the result in bitmap res.

    -

    res can be the same as bitmap1 or bitmap2

    - -
    -
    - -

    ◆ hwloc_bitmap_set()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_set (hwloc_bitmap_t bitmap,
    unsigned id 
    )
    -
    - -

    Add index id in bitmap bitmap.

    - -
    -
    - -

    ◆ hwloc_bitmap_set_ith_ulong()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_set_ith_ulong (hwloc_bitmap_t bitmap,
    unsigned i,
    unsigned long mask 
    )
    -
    - -

    Replace i -th subset of bitmap bitmap with unsigned long mask.

    - -
    -
    - -

    ◆ hwloc_bitmap_set_range()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_set_range (hwloc_bitmap_t bitmap,
    unsigned begin,
    int end 
    )
    -
    - -

    Add indexes from begin to end in bitmap bitmap.

    -

    If end is -1, the range is infinite.

    - -
    -
    - -

    ◆ hwloc_bitmap_singlify()

    - -
    -
    - - - - - - - - -
    int hwloc_bitmap_singlify (hwloc_bitmap_t bitmap)
    -
    - -

    Keep a single index among those set in bitmap bitmap.

    -

    May be useful before binding so that the process does not have a chance of migrating between multiple processors in the original mask. Instead of running the task on any PU inside the given CPU set, the operating system scheduler will be forced to run it on a single of these PUs. It avoids a migration overhead and cache-line ping-pongs between PUs.

    -
    Note
    This function is NOT meant to distribute multiple processes within a single CPU set. It always return the same single bit when called multiple times on the same input set. hwloc_distrib() may be used for generating CPU sets to distribute multiple tasks below a single multi-PU object.
    -
    -This function cannot be applied to an object set directly. It should be applied to a copy (which may be obtained with hwloc_bitmap_dup()).
    - -
    -
    - -

    ◆ hwloc_bitmap_snprintf()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_snprintf (char *restrict buf,
    size_t buflen,
    hwloc_const_bitmap_t bitmap 
    )
    -
    - -

    Stringify a bitmap.

    -

    Up to buflen characters may be written in buffer buf.

    -

    If buflen is 0, buf may safely be NULL.

    -
    Returns
    the number of characters that were actually written if not truncating, or that would have been written (not including the ending \0).
    - -
    -
    - -

    ◆ hwloc_bitmap_sscanf()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_sscanf (hwloc_bitmap_t bitmap,
    const char *restrict string 
    )
    -
    - -

    Parse a bitmap string and stores it in bitmap bitmap.

    -
    Returns
    0 on success, -1 on error.
    - -
    -
    - -

    ◆ hwloc_bitmap_taskset_asprintf()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_taskset_asprintf (char ** strp,
    hwloc_const_bitmap_t bitmap 
    )
    -
    - -

    Stringify a bitmap into a newly allocated taskset-specific string.

    -
    Returns
    0 on success, -1 on error.
    - -
    -
    - -

    ◆ hwloc_bitmap_taskset_snprintf()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_taskset_snprintf (char *restrict buf,
    size_t buflen,
    hwloc_const_bitmap_t bitmap 
    )
    -
    - -

    Stringify a bitmap in the taskset-specific format.

    -

    The taskset command manipulates bitmap strings that contain a single (possible very long) hexadecimal number starting with 0x.

    -

    Up to buflen characters may be written in buffer buf.

    -

    If buflen is 0, buf may safely be NULL.

    -
    Returns
    the number of characters that were actually written if not truncating, or that would have been written (not including the ending \0).
    - -
    -
    - -

    ◆ hwloc_bitmap_taskset_sscanf()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_taskset_sscanf (hwloc_bitmap_t bitmap,
    const char *restrict string 
    )
    -
    - -

    Parse a taskset-specific bitmap string and stores it in bitmap bitmap.

    -
    Returns
    0 on success, -1 on error.
    - -
    -
    - -

    ◆ hwloc_bitmap_to_ith_ulong()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    unsigned long hwloc_bitmap_to_ith_ulong (hwloc_const_bitmap_t bitmap,
    unsigned i 
    )
    -
    - -

    Convert the i -th subset of bitmap bitmap into unsigned long mask.

    - -
    -
    - -

    ◆ hwloc_bitmap_to_ulong()

    - -
    -
    - - - - - - - - -
    unsigned long hwloc_bitmap_to_ulong (hwloc_const_bitmap_t bitmap)
    -
    - -

    Convert the beginning part of bitmap bitmap into unsigned long mask.

    - -
    -
    - -

    ◆ hwloc_bitmap_to_ulongs()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_to_ulongs (hwloc_const_bitmap_t bitmap,
    unsigned nr,
    unsigned long * masks 
    )
    -
    - -

    Convert the first nr subsets of bitmap bitmap into the array of nr unsigned long masks.

    -

    nr may be determined earlier with hwloc_bitmap_nr_ulongs().

    -
    Returns
    0
    - -
    -
    - -

    ◆ hwloc_bitmap_weight()

    - -
    -
    - - - - - - - - -
    int hwloc_bitmap_weight (hwloc_const_bitmap_t bitmap)
    -
    - -

    Compute the "weight" of bitmap bitmap (i.e., number of indexes that are in the bitmap).

    -
    Returns
    the number of indexes that are in the bitmap.
    -
    --1 if bitmap is infinitely set.
    - -
    -
    - -

    ◆ hwloc_bitmap_xor()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_bitmap_xor (hwloc_bitmap_t res,
    hwloc_const_bitmap_t bitmap1,
    hwloc_const_bitmap_t bitmap2 
    )
    -
    - -

    Xor bitmaps bitmap1 and bitmap2 and store the result in bitmap res.

    -

    res can be the same as bitmap1 or bitmap2

    - -
    -
    - -

    ◆ hwloc_bitmap_zero()

    - -
    -
    - - - - - - - - -
    void hwloc_bitmap_zero (hwloc_bitmap_t bitmap)
    -
    - -

    Empty the bitmap bitmap.

    - -
    -
    -
    - - - - - - - -
    -
    -Enumerations | -Functions
    -
    Exporting Topologies to XML
    -
    -
    - - - - -

    -Enumerations

    enum  hwloc_topology_export_xml_flags_e { HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1 - }
     
    - - - - - - - - - - - - - - - -

    -Functions

    int hwloc_topology_export_xml (hwloc_topology_t topology, const char *xmlpath, unsigned long flags)
     
    int hwloc_topology_export_xmlbuffer (hwloc_topology_t topology, char **xmlbuffer, int *buflen, unsigned long flags)
     
    void hwloc_free_xmlbuffer (hwloc_topology_t topology, char *xmlbuffer)
     
    void hwloc_topology_set_userdata_export_callback (hwloc_topology_t topology, void(*export_cb)(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj))
     
    int hwloc_export_obj_userdata (void *reserved, hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length)
     
    int hwloc_export_obj_userdata_base64 (void *reserved, hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length)
     
    void hwloc_topology_set_userdata_import_callback (hwloc_topology_t topology, void(*import_cb)(hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length))
     
    -

    Detailed Description

    -

    Enumeration Type Documentation

    - -

    ◆ hwloc_topology_export_xml_flags_e

    - -
    -
    - - - - -
    enum hwloc_topology_export_xml_flags_e
    -
    - -

    Flags for exporting XML topologies.

    -

    Flags to be given as a OR'ed set to hwloc_topology_export_xml().

    - - -
    Enumerator
    HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1 

    Export XML that is loadable by hwloc v1.x. However, the export may miss some details about the topology.

    -
    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_export_obj_userdata()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_export_obj_userdata (void * reserved,
    hwloc_topology_t topology,
    hwloc_obj_t obj,
    const char * name,
    const void * buffer,
    size_t length 
    )
    -
    - -

    Export some object userdata to XML.

    -

    This function may only be called from within the export() callback passed to hwloc_topology_set_userdata_export_callback(). It may be invoked one of multiple times to export some userdata to XML. The buffer content of length length is stored with optional name name.

    -

    When importing this XML file, the import() callback (if set) will be called exactly as many times as hwloc_export_obj_userdata() was called during export(). It will receive the corresponding name, buffer and length arguments.

    -

    reserved, topology and obj must be the first three parameters that were given to the export callback.

    -

    Only printable characters may be exported to XML string attributes.

    -

    If exporting binary data, the application should first encode into printable characters only (or use hwloc_export_obj_userdata_base64()). It should also take care of portability issues if the export may be reimported on a different architecture.

    -
    Returns
    0 on success.
    -
    --1 with errno set to EINVAL if a non-printable character is passed in name or buffer.
    - -
    -
    - -

    ◆ hwloc_export_obj_userdata_base64()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_export_obj_userdata_base64 (void * reserved,
    hwloc_topology_t topology,
    hwloc_obj_t obj,
    const char * name,
    const void * buffer,
    size_t length 
    )
    -
    - -

    Encode and export some object userdata to XML.

    -

    This function is similar to hwloc_export_obj_userdata() but it encodes the input buffer into printable characters before exporting. On import, decoding is automatically performed before the data is given to the import() callback if any.

    -

    This function may only be called from within the export() callback passed to hwloc_topology_set_userdata_export_callback().

    -

    The name must be made of printable characters for export to XML string attributes.

    -

    The function does not take care of portability issues if the export may be reimported on a different architecture.

    -
    Returns
    0 on success.
    -
    --1 with errno set to EINVAL if a non-printable character is passed in name.
    - -
    -
    - -

    ◆ hwloc_free_xmlbuffer()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    void hwloc_free_xmlbuffer (hwloc_topology_t topology,
    char * xmlbuffer 
    )
    -
    - -

    Free a buffer allocated by hwloc_topology_export_xmlbuffer()

    - -
    -
    - -

    ◆ hwloc_topology_export_xml()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_export_xml (hwloc_topology_t topology,
    const char * xmlpath,
    unsigned long flags 
    )
    -
    - -

    Export the topology into an XML file.

    -

    This file may be loaded later through hwloc_topology_set_xml().

    -

    By default, the latest export format is used, which means older hwloc releases (e.g. v1.x) will not be able to import it. Exporting to v1.x specific XML format is possible using flag HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1 but it may miss some details about the topology. If there is any chance that the exported file may ever be imported back by a process using hwloc 1.x, one should consider detecting it at runtime and using the corresponding export format.

    -

    flags is a OR'ed set of hwloc_topology_export_xml_flags_e.

    -
    Returns
    0 on success, or -1 on error.
    -
    Note
    See also hwloc_topology_set_userdata_export_callback() for exporting application-specific object userdata.
    -
    -The topology-specific userdata pointer is ignored when exporting to XML.
    -
    -Only printable characters may be exported to XML string attributes. Any other character, especially any non-ASCII character, will be silently dropped.
    -
    -If name is "-", the XML output is sent to the standard output.
    - -
    -
    - -

    ◆ hwloc_topology_export_xmlbuffer()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_export_xmlbuffer (hwloc_topology_t topology,
    char ** xmlbuffer,
    int * buflen,
    unsigned long flags 
    )
    -
    - -

    Export the topology into a newly-allocated XML memory buffer.

    -

    xmlbuffer is allocated by the callee and should be freed with hwloc_free_xmlbuffer() later in the caller.

    -

    This memory buffer may be loaded later through hwloc_topology_set_xmlbuffer().

    -

    By default, the latest export format is used, which means older hwloc releases (e.g. v1.x) will not be able to import it. Exporting to v1.x specific XML format is possible using flag HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1 but it may miss some details about the topology. If there is any chance that the exported buffer may ever be imported back by a process using hwloc 1.x, one should consider detecting it at runtime and using the corresponding export format.

    -

    The returned buffer ends with a \0 that is included in the returned length.

    -

    flags is a OR'ed set of hwloc_topology_export_xml_flags_e.

    -
    Returns
    0 on success, or -1 on error.
    -
    Note
    See also hwloc_topology_set_userdata_export_callback() for exporting application-specific object userdata.
    -
    -The topology-specific userdata pointer is ignored when exporting to XML.
    -
    -Only printable characters may be exported to XML string attributes. Any other character, especially any non-ASCII character, will be silently dropped.
    - -
    -
    - -

    ◆ hwloc_topology_set_userdata_export_callback()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    void hwloc_topology_set_userdata_export_callback (hwloc_topology_t topology,
    void(*)(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj) export_cb 
    )
    -
    - -

    Set the application-specific callback for exporting object userdata.

    -

    The object userdata pointer is not exported to XML by default because hwloc does not know what it contains.

    -

    This function lets applications set export_cb to a callback function that converts this opaque userdata into an exportable string.

    -

    export_cb is invoked during XML export for each object whose userdata pointer is not NULL. The callback should use hwloc_export_obj_userdata() or hwloc_export_obj_userdata_base64() to actually export something to XML (possibly multiple times per object).

    -

    export_cb may be set to NULL if userdata should not be exported to XML.

    -
    Note
    The topology-specific userdata pointer is ignored when exporting to XML.
    - -
    -
    - -

    ◆ hwloc_topology_set_userdata_import_callback()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    void hwloc_topology_set_userdata_import_callback (hwloc_topology_t topology,
    void(*)(hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length) import_cb 
    )
    -
    - -

    Set the application-specific callback for importing userdata.

    -

    On XML import, userdata is ignored by default because hwloc does not know how to store it in memory.

    -

    This function lets applications set import_cb to a callback function that will get the XML-stored userdata and store it in the object as expected by the application.

    -

    import_cb is called during hwloc_topology_load() as many times as hwloc_export_obj_userdata() was called during export. The topology is not entirely setup yet. Object attributes are ready to consult, but links between objects are not.

    -

    import_cb may be NULL if userdata should be ignored during import.

    -
    Note
    buffer contains length characters followed by a null byte ('\0').
    -
    -This function should be called before hwloc_topology_load().
    -
    -The topology-specific userdata pointer is ignored when importing from XML.
    - -
    -
    -
    - - - - - - - -
    -
    -Enumerations | -Functions
    -
    Exporting Topologies to Synthetic
    -
    -
    - - - - -

    -Enumerations

    enum  hwloc_topology_export_synthetic_flags_e { HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_EXTENDED_TYPES -, HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_ATTRS -, HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_V1 -, HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_IGNORE_MEMORY - }
     
    - - - -

    -Functions

    int hwloc_topology_export_synthetic (hwloc_topology_t topology, char *buffer, size_t buflen, unsigned long flags)
     
    -

    Detailed Description

    -

    Enumeration Type Documentation

    - -

    ◆ hwloc_topology_export_synthetic_flags_e

    - -
    -
    - - - - -
    enum hwloc_topology_export_synthetic_flags_e
    -
    - -

    Flags for exporting synthetic topologies.

    -

    Flags to be given as a OR'ed set to hwloc_topology_export_synthetic().

    - - - - - -
    Enumerator
    HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_EXTENDED_TYPES 

    Export extended types such as L2dcache as basic types such as Cache.

    -

    This is required if loading the synthetic description with hwloc < 1.9.

    -
    HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_NO_ATTRS 

    Do not export level attributes.

    -

    Ignore level attributes such as memory/cache sizes or PU indexes. This is required if loading the synthetic description with hwloc < 1.10.

    -
    HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_V1 

    Export the memory hierarchy as expected in hwloc 1.x.

    -

    Instead of attaching memory children to levels, export single NUMA node child as normal intermediate levels, when possible. This is required if loading the synthetic description with hwloc 1.x. However this may fail if some objects have multiple local NUMA nodes.

    -
    HWLOC_TOPOLOGY_EXPORT_SYNTHETIC_FLAG_IGNORE_MEMORY 

    Do not export memory information.

    -

    Only export the actual hierarchy of normal CPU-side objects and ignore where memory is attached. This is useful for when the hierarchy of CPUs is what really matters, but it behaves as if there was a single machine-wide NUMA node.

    -
    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_topology_export_synthetic()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_export_synthetic (hwloc_topology_t topology,
    char * buffer,
    size_t buflen,
    unsigned long flags 
    )
    -
    - -

    Export the topology as a synthetic string.

    -

    At most buflen characters will be written in buffer, including the terminating \0.

    -

    This exported string may be given back to hwloc_topology_set_synthetic().

    -

    flags is a OR'ed set of hwloc_topology_export_synthetic_flags_e.

    -
    Returns
    The number of characters that were written, not including the terminating \0.
    -
    --1 if the topology could not be exported, for instance if it is not symmetric.
    -
    Note
    I/O and Misc children are ignored, the synthetic string only describes normal children.
    -
    -A 1024-byte buffer should be large enough for exporting topologies in the vast majority of cases.
    - -
    -
    -
    - - - - - - - -
    -
    -Data Structures | -Enumerations | -Functions
    -
    Retrieve distances between objects
    -
    -
    - - - - -

    -Data Structures

    struct  hwloc_distances_s
     
    - - - - - -

    -Enumerations

    enum  hwloc_distances_kind_e {
    -  HWLOC_DISTANCES_KIND_FROM_OS -, HWLOC_DISTANCES_KIND_FROM_USER -, HWLOC_DISTANCES_KIND_MEANS_LATENCY -, HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH -,
    -  HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES -
    - }
     
    enum  hwloc_distances_transform_e { HWLOC_DISTANCES_TRANSFORM_REMOVE_NULL -, HWLOC_DISTANCES_TRANSFORM_LINKS -, HWLOC_DISTANCES_TRANSFORM_MERGE_SWITCH_PORTS -, HWLOC_DISTANCES_TRANSFORM_TRANSITIVE_CLOSURE - }
     
    - - - - - - - - - - - - - - - -

    -Functions

    int hwloc_distances_get (hwloc_topology_t topology, unsigned *nr, struct hwloc_distances_s **distances, unsigned long kind, unsigned long flags)
     
    int hwloc_distances_get_by_depth (hwloc_topology_t topology, int depth, unsigned *nr, struct hwloc_distances_s **distances, unsigned long kind, unsigned long flags)
     
    int hwloc_distances_get_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned *nr, struct hwloc_distances_s **distances, unsigned long kind, unsigned long flags)
     
    int hwloc_distances_get_by_name (hwloc_topology_t topology, const char *name, unsigned *nr, struct hwloc_distances_s **distances, unsigned long flags)
     
    const char * hwloc_distances_get_name (hwloc_topology_t topology, struct hwloc_distances_s *distances)
     
    void hwloc_distances_release (hwloc_topology_t topology, struct hwloc_distances_s *distances)
     
    int hwloc_distances_transform (hwloc_topology_t topology, struct hwloc_distances_s *distances, enum hwloc_distances_transform_e transform, void *transform_attr, unsigned long flags)
     
    -

    Detailed Description

    -

    Enumeration Type Documentation

    - -

    ◆ hwloc_distances_kind_e

    - -
    -
    - - - - -
    enum hwloc_distances_kind_e
    -
    - -

    Kinds of distance matrices.

    -

    The kind attribute of struct hwloc_distances_s is a OR'ed set of kinds.

    -

    A kind of format HWLOC_DISTANCES_KIND_FROM_* specifies where the distance information comes from, if known.

    -

    A kind of format HWLOC_DISTANCES_KIND_MEANS_* specifies whether values are latencies or bandwidths, if applicable.

    - - - - - - -
    Enumerator
    HWLOC_DISTANCES_KIND_FROM_OS 

    These distances were obtained from the operating system or hardware.

    -
    HWLOC_DISTANCES_KIND_FROM_USER 

    These distances were provided by the user.

    -
    HWLOC_DISTANCES_KIND_MEANS_LATENCY 

    Distance values are similar to latencies between objects. Values are smaller for closer objects, hence minimal on the diagonal of the matrix (distance between an object and itself). It could also be the number of network hops between objects, etc.

    -
    HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH 

    Distance values are similar to bandwidths between objects. Values are higher for closer objects, hence maximal on the diagonal of the matrix (distance between an object and itself). Such values are currently ignored for distance-based grouping.

    -
    HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES 

    This distances structure covers objects of different types. This may apply to the "NVLinkBandwidth" structure in presence of a NVSwitch or POWER processor NVLink port.

    -
    - -
    -
    - -

    ◆ hwloc_distances_transform_e

    - -
    -
    - - - - -
    enum hwloc_distances_transform_e
    -
    - -

    Transformations of distances structures.

    - - - - - -
    Enumerator
    HWLOC_DISTANCES_TRANSFORM_REMOVE_NULL 

    Remove NULL objects from the distances structure.

    -

    Every object that was replaced with NULL in the objs array is removed and the values array is updated accordingly.

    -

    At least 2 objects must remain, otherwise hwloc_distances_transform() will return -1 with errno set to EINVAL.

    -

    kind will be updated with or without HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES according to the remaining objects.

    -
    HWLOC_DISTANCES_TRANSFORM_LINKS 

    Replace bandwidth values with a number of links.

    -

    Usually all values will be either 0 (no link) or 1 (one link). However some matrices could get larger values if some pairs of peers are connected by different numbers of links.

    -

    Values on the diagonal are set to 0.

    -

    This transformation only applies to bandwidth matrices.

    -
    HWLOC_DISTANCES_TRANSFORM_MERGE_SWITCH_PORTS 

    Merge switches with multiple ports into a single object. This currently only applies to NVSwitches where GPUs seem connected to different separate switch ports in the NVLinkBandwidth matrix. This transformation will replace all of them with the same port connected to all GPUs. Other ports are removed by applying HWLOC_DISTANCES_TRANSFORM_REMOVE_NULL internally.

    -
    HWLOC_DISTANCES_TRANSFORM_TRANSITIVE_CLOSURE 

    Apply a transitive closure to the matrix to connect objects across switches. This currently only applies to GPUs and NVSwitches in the NVLinkBandwidth matrix. All pairs of GPUs will be reported as directly connected.

    -
    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_distances_get()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_distances_get (hwloc_topology_t topology,
    unsigned * nr,
    struct hwloc_distances_s ** distances,
    unsigned long kind,
    unsigned long flags 
    )
    -
    - -

    Retrieve distance matrices.

    -

    Retrieve distance matrices from the topology into the distances array.

    -

    flags is currently unused, should be 0.

    -

    kind serves as a filter. If 0, all distance matrices are returned. If it contains some HWLOC_DISTANCES_KIND_FROM_*, only distance matrices whose kind matches one of these are returned. If it contains some HWLOC_DISTANCES_KIND_MEANS_*, only distance matrices whose kind matches one of these are returned.

    -

    On input, nr points to the number of distance matrices that may be stored in distances. On output, nr points to the number of distance matrices that were actually found, even if some of them couldn't be stored in distances. Distance matrices that couldn't be stored are ignored, but the function still returns success (0). The caller may find out by comparing the value pointed by nr before and after the function call.

    -

    Each distance matrix returned in the distances array should be released by the caller using hwloc_distances_release().

    -
    Returns
    0 on success, -1 on error.
    - -
    -
    - -

    ◆ hwloc_distances_get_by_depth()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_distances_get_by_depth (hwloc_topology_t topology,
    int depth,
    unsigned * nr,
    struct hwloc_distances_s ** distances,
    unsigned long kind,
    unsigned long flags 
    )
    -
    - -

    Retrieve distance matrices for object at a specific depth in the topology.

    -

    Identical to hwloc_distances_get() with the additional depth filter.

    -
    Returns
    0 on success, -1 on error.
    - -
    -
    - -

    ◆ hwloc_distances_get_by_name()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_distances_get_by_name (hwloc_topology_t topology,
    const char * name,
    unsigned * nr,
    struct hwloc_distances_s ** distances,
    unsigned long flags 
    )
    -
    - -

    Retrieve a distance matrix with the given name.

    -

    Usually only one distances structure may match a given name.

    -

    The name of the most common structure is "NUMALatency". Others include "XGMIBandwidth", "XGMIHops", "XeLinkBandwidth", and "NVLinkBandwidth".

    -
    Returns
    0 on success, -1 on error.
    - -
    -
    - -

    ◆ hwloc_distances_get_by_type()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_distances_get_by_type (hwloc_topology_t topology,
    hwloc_obj_type_t type,
    unsigned * nr,
    struct hwloc_distances_s ** distances,
    unsigned long kind,
    unsigned long flags 
    )
    -
    - -

    Retrieve distance matrices for object of a specific type.

    -

    Identical to hwloc_distances_get() with the additional type filter.

    -
    Returns
    0 on success, -1 on error.
    - -
    -
    - -

    ◆ hwloc_distances_get_name()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    const char * hwloc_distances_get_name (hwloc_topology_t topology,
    struct hwloc_distances_s * distances 
    )
    -
    - -

    Get a description of what a distances structure contains.

    -

    For instance "NUMALatency" for hardware-provided NUMA distances (ACPI SLIT), or NULL if unknown.

    -
    Returns
    the constant string with the name of the distance structure.
    -
    Note
    The returned name should not be freed by the caller, it belongs to the hwloc library.
    - -
    -
    - -

    ◆ hwloc_distances_release()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    void hwloc_distances_release (hwloc_topology_t topology,
    struct hwloc_distances_s * distances 
    )
    -
    - -

    Release a distance matrix structure previously returned by hwloc_distances_get().

    -
    Note
    This function is not required if the structure is removed with hwloc_distances_release_remove().
    - -
    -
    - -

    ◆ hwloc_distances_transform()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_distances_transform (hwloc_topology_t topology,
    struct hwloc_distances_s * distances,
    enum hwloc_distances_transform_e transform,
    void * transform_attr,
    unsigned long flags 
    )
    -
    - -

    Apply a transformation to a distances structure.

    -

    Modify a distances structure that was previously obtained with hwloc_distances_get() or one of its variants.

    -

    This modifies the local copy of the distances structures but does not modify the distances information stored inside the topology (retrieved by another call to hwloc_distances_get() or exported to XML). To do so, one should add a new distances structure with same name, kind, objects and values (see Add distances between objects) and then remove this old one with hwloc_distances_release_remove().

    -

    transform must be one of the transformations listed in hwloc_distances_transform_e.

    -

    These transformations may modify the contents of the objs or values arrays.

    -

    transform_attr must be NULL for now.

    -

    flags must be 0 for now.

    -
    Returns
    0 on success, -1 on error for instance if flags are invalid.
    -
    Note
    Objects in distances array objs may be directly modified in place without using hwloc_distances_transform(). One may use hwloc_get_obj_with_same_locality() to easily convert between similar objects of different types.
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    Helpers for consulting distance matrices
    -
    -
    - - - - - - -

    -Functions

    static int hwloc_distances_obj_index (struct hwloc_distances_s *distances, hwloc_obj_t obj)
     
    static int hwloc_distances_obj_pair_values (struct hwloc_distances_s *distances, hwloc_obj_t obj1, hwloc_obj_t obj2, hwloc_uint64_t *value1to2, hwloc_uint64_t *value2to1)
     
    -

    Detailed Description

    -

    Function Documentation

    - -

    ◆ hwloc_distances_obj_index()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static int hwloc_distances_obj_index (struct hwloc_distances_s * distances,
    hwloc_obj_t obj 
    )
    -     		-inlinestatic
    -
    - -

    Find the index of an object in a distances structure.

    -
    Returns
    the index of the object in the distances structure if any.
    -
    --1 if object obj is not involved in structure distances.
    - -
    -
    - -

    ◆ hwloc_distances_obj_pair_values()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_distances_obj_pair_values (struct hwloc_distances_s * distances,
    hwloc_obj_t obj1,
    hwloc_obj_t obj2,
    hwloc_uint64_t * value1to2,
    hwloc_uint64_t * value2to1 
    )
    -     		-inlinestatic
    -
    - -

    Find the values between two objects in a distance matrices.

    -

    The distance from obj1 to obj2 is stored in the value pointed by value1to2 and reciprocally.

    -
    Returns
    0 on success.
    -
    --1 if object obj1 or obj2 is not involved in structure distances.
    - -
    -
    -
    - - - - - - - -
    -
    -Typedefs | -Enumerations | -Functions
    -
    Add distances between objects
    -
    -
    - - - - -

    -Typedefs

    typedef void * hwloc_distances_add_handle_t
     
    - - - -

    -Enumerations

    enum  hwloc_distances_add_flag_e { HWLOC_DISTANCES_ADD_FLAG_GROUP -, HWLOC_DISTANCES_ADD_FLAG_GROUP_INACCURATE - }
     
    - - - - - - - -

    -Functions

    hwloc_distances_add_handle_t hwloc_distances_add_create (hwloc_topology_t topology, const char *name, unsigned long kind, unsigned long flags)
     
    int hwloc_distances_add_values (hwloc_topology_t topology, hwloc_distances_add_handle_t handle, unsigned nbobjs, hwloc_obj_t *objs, hwloc_uint64_t *values, unsigned long flags)
     
    int hwloc_distances_add_commit (hwloc_topology_t topology, hwloc_distances_add_handle_t handle, unsigned long flags)
     
    -

    Detailed Description

    -

    The usual way to add distances is:

    hwloc_distances_add_handle_t handle;
    -
    int err = -1;
    -
    handle = hwloc_distances_add_create(topology, "name", kind, 0);
    -
    if (handle) {
    -
    err = hwloc_distances_add_values(topology, handle, nbobjs, objs, values, 0);
    -
    if (!err)
    -
    err = hwloc_distances_add_commit(topology, handle, flags);
    -
    }
    -
    hwloc_distances_add_commit
    int hwloc_distances_add_commit(hwloc_topology_t topology, hwloc_distances_add_handle_t handle, unsigned long flags)
    Commit a new distances structure.
    -
    hwloc_distances_add_handle_t
    void * hwloc_distances_add_handle_t
    Handle to a new distances structure during its addition to the topology.
    Definition: distances.h:348
    -
    hwloc_distances_add_create
    hwloc_distances_add_handle_t hwloc_distances_add_create(hwloc_topology_t topology, const char *name, unsigned long kind, unsigned long flags)
    Create a new empty distances structure.
    -
    hwloc_distances_add_values
    int hwloc_distances_add_values(hwloc_topology_t topology, hwloc_distances_add_handle_t handle, unsigned nbobjs, hwloc_obj_t *objs, hwloc_uint64_t *values, unsigned long flags)
    Specify the objects and values in a new empty distances structure.
    -

    If err is 0 at the end, then addition was successful.

    -

    Typedef Documentation

    - -

    ◆ hwloc_distances_add_handle_t

    - -
    -
    - - - - -
    typedef void* hwloc_distances_add_handle_t
    -
    - -

    Handle to a new distances structure during its addition to the topology.

    - -
    -
    -

    Enumeration Type Documentation

    - -

    ◆ hwloc_distances_add_flag_e

    - -
    -
    - - - - -
    enum hwloc_distances_add_flag_e
    -
    - -

    Flags for adding a new distances to a topology.

    - - - -
    Enumerator
    HWLOC_DISTANCES_ADD_FLAG_GROUP 

    Try to group objects based on the newly provided distance information. This is ignored for distances between objects of different types.

    -
    HWLOC_DISTANCES_ADD_FLAG_GROUP_INACCURATE 

    If grouping, consider the distance values as inaccurate and relax the comparisons during the grouping algorithms. The actual accuracy may be modified through the HWLOC_GROUPING_ACCURACY environment variable (see Environment Variables).

    -
    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_distances_add_commit()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_distances_add_commit (hwloc_topology_t topology,
    hwloc_distances_add_handle_t handle,
    unsigned long flags 
    )
    -
    - -

    Commit a new distances structure.

    -

    This function finalizes the distances structure and inserts in it the topology.

    -

    Parameter handle was previously returned by hwloc_distances_add_create(). Then objects and values were specified with hwloc_distances_add_values().

    -

    flags configures the behavior of the function using an optional OR'ed set of hwloc_distances_add_flag_e. It may be used to request the grouping of existing objects based on distances.

    -

    On error, the temporary distances structure and its content are destroyed.

    -
    Returns
    0 on success.
    -
    --1 on error.
    - -
    -
    - -

    ◆ hwloc_distances_add_create()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    hwloc_distances_add_handle_t hwloc_distances_add_create (hwloc_topology_t topology,
    const char * name,
    unsigned long kind,
    unsigned long flags 
    )
    -
    - -

    Create a new empty distances structure.

    -

    Create an empty distances structure to be filled with hwloc_distances_add_values() and then committed with hwloc_distances_add_commit().

    -

    Parameter name is optional, it may be NULL. Otherwise, it will be copied internally and may later be freed by the caller.

    -

    kind specifies the kind of distance as a OR'ed set of hwloc_distances_kind_e. Kind HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES will be automatically set according to objects having different types in hwloc_distances_add_values().

    -

    flags must be 0 for now.

    -
    Returns
    A hwloc_distances_add_handle_t that should then be passed to hwloc_distances_add_values() and hwloc_distances_add_commit().
    -
    -NULL on error.
    - -
    -
    - -

    ◆ hwloc_distances_add_values()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_distances_add_values (hwloc_topology_t topology,
    hwloc_distances_add_handle_t handle,
    unsigned nbobjs,
    hwloc_obj_t * objs,
    hwloc_uint64_t * values,
    unsigned long flags 
    )
    -
    - -

    Specify the objects and values in a new empty distances structure.

    -

    Specify the objects and values for a new distances structure that was returned as a handle by hwloc_distances_add_create(). The structure must then be committed with hwloc_distances_add_commit().

    -

    The number of objects is nbobjs and the array of objects is objs. Distance values are stored as a one-dimension array in values. The distance from object i to object j is in slot i*nbobjs+j.

    -

    nbobjs must be at least 2.

    -

    Arrays objs and values will be copied internally, they may later be freed by the caller.

    -

    On error, the temporary distances structure and its content are destroyed.

    -

    flags must be 0 for now.

    -
    Returns
    0 on success.
    -
    --1 on error.
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    Remove distances between objects
    -
    -
    - - - - - - - - - - -

    -Functions

    int hwloc_distances_remove (hwloc_topology_t topology)
     
    int hwloc_distances_remove_by_depth (hwloc_topology_t topology, int depth)
     
    static int hwloc_distances_remove_by_type (hwloc_topology_t topology, hwloc_obj_type_t type)
     
    int hwloc_distances_release_remove (hwloc_topology_t topology, struct hwloc_distances_s *distances)
     
    -

    Detailed Description

    -

    Function Documentation

    - -

    ◆ hwloc_distances_release_remove()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_distances_release_remove (hwloc_topology_t topology,
    struct hwloc_distances_s * distances 
    )
    -
    - -

    Release and remove the given distance matrice from the topology.

    -

    This function includes a call to hwloc_distances_release().

    -
    Returns
    0 on success, -1 on error.
    - -
    -
    - -

    ◆ hwloc_distances_remove()

    - -
    -
    - - - - - - - - -
    int hwloc_distances_remove (hwloc_topology_t topology)
    -
    - -

    Remove all distance matrices from a topology.

    -

    Remove all distance matrices, either provided by the user or gathered through the OS.

    -

    If these distances were used to group objects, these additional Group objects are not removed from the topology.

    -
    Returns
    0 on success, -1 on error.
    - -
    -
    - -

    ◆ hwloc_distances_remove_by_depth()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_distances_remove_by_depth (hwloc_topology_t topology,
    int depth 
    )
    -
    - -

    Remove distance matrices for objects at a specific depth in the topology.

    -

    Identical to hwloc_distances_remove() but only applies to one level of the topology.

    -
    Returns
    0 on success, -1 on error.
    - -
    -
    - -

    ◆ hwloc_distances_remove_by_type()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static int hwloc_distances_remove_by_type (hwloc_topology_t topology,
    hwloc_obj_type_t type 
    )
    -     		-inlinestatic
    -
    - -

    Remove distance matrices for objects of a specific type in the topology.

    -

    Identical to hwloc_distances_remove() but only applies to one level of the topology.

    -
    Returns
    0 on success, -1 on error.
    - -
    -
    -
    - - - - - - - -
    -
    -Data Structures | -Typedefs | -Enumerations | -Functions
    -
    Comparing memory node attributes for finding where to allocate on
    -
    -
    - - - - -

    -Data Structures

    struct  hwloc_location
     
    - - - -

    -Typedefs

    typedef unsigned hwloc_memattr_id_t
     
    - - - - - - - -

    -Enumerations

    enum  hwloc_memattr_id_e {
    -  HWLOC_MEMATTR_ID_CAPACITY -, HWLOC_MEMATTR_ID_LOCALITY -, HWLOC_MEMATTR_ID_BANDWIDTH -, HWLOC_MEMATTR_ID_READ_BANDWIDTH -,
    -  HWLOC_MEMATTR_ID_WRITE_BANDWIDTH -, HWLOC_MEMATTR_ID_LATENCY -, HWLOC_MEMATTR_ID_READ_LATENCY -, HWLOC_MEMATTR_ID_WRITE_LATENCY -,
    -  HWLOC_MEMATTR_ID_MAX -
    - }
     
    enum  hwloc_location_type_e { HWLOC_LOCATION_TYPE_CPUSET -, HWLOC_LOCATION_TYPE_OBJECT - }
     
    enum  hwloc_local_numanode_flag_e { HWLOC_LOCAL_NUMANODE_FLAG_LARGER_LOCALITY -, HWLOC_LOCAL_NUMANODE_FLAG_SMALLER_LOCALITY -, HWLOC_LOCAL_NUMANODE_FLAG_ALL - }
     
    - - - - - - - - - - - -

    -Functions

    int hwloc_memattr_get_by_name (hwloc_topology_t topology, const char *name, hwloc_memattr_id_t *id)
     
    int hwloc_get_local_numanode_objs (hwloc_topology_t topology, struct hwloc_location *location, unsigned *nr, hwloc_obj_t *nodes, unsigned long flags)
     
    int hwloc_memattr_get_value (hwloc_topology_t topology, hwloc_memattr_id_t attribute, hwloc_obj_t target_node, struct hwloc_location *initiator, unsigned long flags, hwloc_uint64_t *value)
     
    int hwloc_memattr_get_best_target (hwloc_topology_t topology, hwloc_memattr_id_t attribute, struct hwloc_location *initiator, unsigned long flags, hwloc_obj_t *best_target, hwloc_uint64_t *value)
     
    int hwloc_memattr_get_best_initiator (hwloc_topology_t topology, hwloc_memattr_id_t attribute, hwloc_obj_t target, unsigned long flags, struct hwloc_location *best_initiator, hwloc_uint64_t *value)
     
    -

    Detailed Description

    -

    Platforms with heterogeneous memory require ways to decide whether a buffer should be allocated on "fast" memory (such as HBM), "normal" memory (DDR) or even "slow" but large-capacity memory (non-volatile memory). These memory nodes are called "Targets" while the CPU accessing them is called the "Initiator". Access performance depends on their locality (NUMA platforms) as well as the intrinsic performance of the targets (heterogeneous platforms).

    -

    The following attributes describe the performance of memory accesses from an Initiator to a memory Target, for instance their latency or bandwidth. Initiators performing these memory accesses are usually some PUs or Cores (described as a CPU set). Hence a Core may choose where to allocate a memory buffer by comparing the attributes of different target memory nodes nearby.

    -

    There are also some attributes that are system-wide. Their value does not depend on a specific initiator performing an access. The memory node Capacity is an example of such attribute without initiator.

    -

    One way to use this API is to start with a cpuset describing the Cores where a program is bound. The best target NUMA node for allocating memory in this program on these Cores may be obtained by passing this cpuset as an initiator to hwloc_memattr_get_best_target() with the relevant memory attribute. For instance, if the code is latency limited, use the Latency attribute.

    -

    A more flexible approach consists in getting the list of local NUMA nodes by passing this cpuset to hwloc_get_local_numanode_objs(). Attribute values for these nodes, if any, may then be obtained with hwloc_memattr_get_value() and manually compared with the desired criteria.

    -
    See also
    An example is available in doc/examples/memory-attributes.c in the source tree.
    -
    Note
    The API also supports specific objects as initiator, but it is currently not used internally by hwloc. Users may for instance use it to provide custom performance values for host memory accesses performed by GPUs.
    -
    -The interface actually also accepts targets that are not NUMA nodes.
    -

    Typedef Documentation

    - -

    ◆ hwloc_memattr_id_t

    - -
    -
    - - - - -
    typedef unsigned hwloc_memattr_id_t
    -
    - -

    A memory attribute identifier. May be either one of hwloc_memattr_id_e or a new id returned by hwloc_memattr_register().

    - -
    -
    -

    Enumeration Type Documentation

    - -

    ◆ hwloc_local_numanode_flag_e

    - -
    -
    - - - - -
    enum hwloc_local_numanode_flag_e
    -
    - -

    Flags for selecting target NUMA nodes.

    - - - - -
    Enumerator
    HWLOC_LOCAL_NUMANODE_FLAG_LARGER_LOCALITY 

    Select NUMA nodes whose locality is larger than the given cpuset. For instance, if a single PU (or its cpuset) is given in initiator, select all nodes close to the package that contains this PU.

    -
    HWLOC_LOCAL_NUMANODE_FLAG_SMALLER_LOCALITY 

    Select NUMA nodes whose locality is smaller than the given cpuset. For instance, if a package (or its cpuset) is given in initiator, also select nodes that are attached to only a half of that package.

    -
    HWLOC_LOCAL_NUMANODE_FLAG_ALL 

    Select all NUMA nodes in the topology. The initiator initiator is ignored.

    -
    - -
    -
    - -

    ◆ hwloc_location_type_e

    - -
    -
    - - - - -
    enum hwloc_location_type_e
    -
    - -

    Type of location.

    - - - -
    Enumerator
    HWLOC_LOCATION_TYPE_CPUSET 

    Location is given as a cpuset, in the location cpuset union field.

    -
    HWLOC_LOCATION_TYPE_OBJECT 

    Location is given as an object, in the location object union field.

    -
    - -
    -
    - -

    ◆ hwloc_memattr_id_e

    - -
    -
    - - - - -
    enum hwloc_memattr_id_e
    -
    - -

    Memory node attributes.

    - - - - - - - - - -
    Enumerator
    HWLOC_MEMATTR_ID_CAPACITY 

    The "Capacity" is returned in bytes (local_memory attribute in objects).

    -

    Best capacity nodes are nodes with higher capacity.

    -

    No initiator is involved when looking at this attribute. The corresponding attribute flags are HWLOC_MEMATTR_FLAG_HIGHER_FIRST.

    -
    HWLOC_MEMATTR_ID_LOCALITY 

    The "Locality" is returned as the number of PUs in that locality (e.g. the weight of its cpuset).

    -

    Best locality nodes are nodes with smaller locality (nodes that are local to very few PUs). Poor locality nodes are nodes with larger locality (nodes that are local to the entire machine).

    -

    No initiator is involved when looking at this attribute. The corresponding attribute flags are HWLOC_MEMATTR_FLAG_HIGHER_FIRST.

    -
    HWLOC_MEMATTR_ID_BANDWIDTH 

    The "Bandwidth" is returned in MiB/s, as seen from the given initiator location.

    -

    Best bandwidth nodes are nodes with higher bandwidth.

    -

    The corresponding attribute flags are HWLOC_MEMATTR_FLAG_HIGHER_FIRST and HWLOC_MEMATTR_FLAG_NEED_INITIATOR.

    -

    This is the average bandwidth for read and write accesses. If the platform provides individual read and write bandwidths but no explicit average value, hwloc computes and returns the average.

    -
    HWLOC_MEMATTR_ID_READ_BANDWIDTH 

    The "ReadBandwidth" is returned in MiB/s, as seen from the given initiator location.

    -

    Best bandwidth nodes are nodes with higher bandwidth.

    -

    The corresponding attribute flags are HWLOC_MEMATTR_FLAG_HIGHER_FIRST and HWLOC_MEMATTR_FLAG_NEED_INITIATOR.

    -
    HWLOC_MEMATTR_ID_WRITE_BANDWIDTH 

    The "WriteBandwidth" is returned in MiB/s, as seen from the given initiator location.

    -

    Best bandwidth nodes are nodes with higher bandwidth.

    -

    The corresponding attribute flags are HWLOC_MEMATTR_FLAG_HIGHER_FIRST and HWLOC_MEMATTR_FLAG_NEED_INITIATOR.

    -
    HWLOC_MEMATTR_ID_LATENCY 

    The "Latency" is returned as nanoseconds, as seen from the given initiator location.

    -

    Best latency nodes are nodes with smaller latency.

    -

    The corresponding attribute flags are HWLOC_MEMATTR_FLAG_LOWER_FIRST and HWLOC_MEMATTR_FLAG_NEED_INITIATOR.

    -

    This is the average latency for read and write accesses. If the platform provides individual read and write latencies but no explicit average value, hwloc computes and returns the average.

    -
    HWLOC_MEMATTR_ID_READ_LATENCY 

    The "ReadLatency" is returned as nanoseconds, as seen from the given initiator location.

    -

    Best latency nodes are nodes with smaller latency.

    -

    The corresponding attribute flags are HWLOC_MEMATTR_FLAG_LOWER_FIRST and HWLOC_MEMATTR_FLAG_NEED_INITIATOR.

    -
    HWLOC_MEMATTR_ID_WRITE_LATENCY 

    The "WriteLatency" is returned as nanoseconds, as seen from the given initiator location.

    -

    Best latency nodes are nodes with smaller latency.

    -

    The corresponding attribute flags are HWLOC_MEMATTR_FLAG_LOWER_FIRST and HWLOC_MEMATTR_FLAG_NEED_INITIATOR.

    -
    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_get_local_numanode_objs()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_get_local_numanode_objs (hwloc_topology_t topology,
    struct hwloc_location * location,
    unsigned * nr,
    hwloc_obj_t * nodes,
    unsigned long flags 
    )
    -
    - -

    Return an array of local NUMA nodes.

    -

    By default only select the NUMA nodes whose locality is exactly the given location. More nodes may be selected if additional flags are given as a OR'ed set of hwloc_local_numanode_flag_e.

    -

    If location is given as an explicit object, its CPU set is used to find NUMA nodes with the corresponding locality. If the object does not have a CPU set (e.g. I/O object), the CPU parent (where the I/O object is attached) is used.

    -

    On input, nr points to the number of nodes that may be stored in the nodes array. On output, nr will be changed to the number of stored nodes, or the number of nodes that would have been stored if there were enough room.

    -
    Returns
    0 on success or -1 on error.
    -
    Note
    Some of these NUMA nodes may not have any memory attribute values and hence not be reported as actual targets in other functions.
    -
    -The number of NUMA nodes in the topology (obtained by hwloc_bitmap_weight() on the root object nodeset) may be used to allocate the nodes array.
    -
    -When an object CPU set is given as locality, for instance a Package, and when flags contain both HWLOC_LOCAL_NUMANODE_FLAG_LARGER_LOCALITY and HWLOC_LOCAL_NUMANODE_FLAG_SMALLER_LOCALITY, the returned array corresponds to the nodeset of that object.
    - -
    -
    - -

    ◆ hwloc_memattr_get_best_initiator()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_memattr_get_best_initiator (hwloc_topology_t topology,
    hwloc_memattr_id_t attribute,
    hwloc_obj_t target,
    unsigned long flags,
    struct hwloc_location * best_initiator,
    hwloc_uint64_t * value 
    )
    -
    - -

    Return the best initiator for the given attribute and target NUMA node.

    -

    If value is non NULL, the corresponding value is returned there.

    -

    If multiple initiators have the same attribute values, only one is returned (and there is no way to clarify how that one is chosen). Applications that want to detect initiators with identical/similar values, or that want to look at values for multiple attributes, should rather get all values using hwloc_memattr_get_value() and manually select the initiator they consider the best.

    -

    The returned initiator should not be modified or freed, it belongs to the topology.

    -

    flags must be 0 for now.

    -
    Returns
    0 on success.
    -
    --1 with errno set to ENOENT if there are no matching initiators.
    -
    --1 with errno set to EINVAL if the attribute does not relate to a specific initiator (it does not have the flag HWLOC_MEMATTR_FLAG_NEED_INITIATOR).
    - -
    -
    - -

    ◆ hwloc_memattr_get_best_target()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_memattr_get_best_target (hwloc_topology_t topology,
    hwloc_memattr_id_t attribute,
    struct hwloc_location * initiator,
    unsigned long flags,
    hwloc_obj_t * best_target,
    hwloc_uint64_t * value 
    )
    -
    - -

    Return the best target NUMA node for the given attribute and initiator.

    -

    If the attribute does not relate to a specific initiator (it does not have the flag HWLOC_MEMATTR_FLAG_NEED_INITIATOR), location initiator is ignored and may be NULL.

    -

    If value is non NULL, the corresponding value is returned there.

    -

    If multiple targets have the same attribute values, only one is returned (and there is no way to clarify how that one is chosen). Applications that want to detect targets with identical/similar values, or that want to look at values for multiple attributes, should rather get all values using hwloc_memattr_get_value() and manually select the target they consider the best.

    -

    flags must be 0 for now.

    -
    Returns
    0 on success.
    -
    --1 with errno set to ENOENT if there are no matching targets.
    -
    --1 with errno set to EINVAL if flags are invalid, or no such attribute exists.
    -
    Note
    The initiator initiator should be of type HWLOC_LOCATION_TYPE_CPUSET when refering to accesses performed by CPU cores. HWLOC_LOCATION_TYPE_OBJECT is currently unused internally by hwloc, but users may for instance use it to provide custom information about host memory accesses performed by GPUs.
    - -
    -
    - -

    ◆ hwloc_memattr_get_by_name()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_memattr_get_by_name (hwloc_topology_t topology,
    const char * name,
    hwloc_memattr_id_t * id 
    )
    -
    - -

    Return the identifier of the memory attribute with the given name.

    -
    Returns
    0 on success.
    -
    --1 with errno set to EINVAL if no such attribute exists.
    - -
    -
    - -

    ◆ hwloc_memattr_get_value()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_memattr_get_value (hwloc_topology_t topology,
    hwloc_memattr_id_t attribute,
    hwloc_obj_t target_node,
    struct hwloc_location * initiator,
    unsigned long flags,
    hwloc_uint64_t * value 
    )
    -
    - -

    Return an attribute value for a specific target NUMA node.

    -

    If the attribute does not relate to a specific initiator (it does not have the flag HWLOC_MEMATTR_FLAG_NEED_INITIATOR), location initiator is ignored and may be NULL.

    -

    flags must be 0 for now.

    -
    Returns
    0 on success.
    -
    --1 on error, for instance with errno set to EINVAL if flags are invalid or no such attribute exists.
    -
    Note
    The initiator initiator should be of type HWLOC_LOCATION_TYPE_CPUSET when refering to accesses performed by CPU cores. HWLOC_LOCATION_TYPE_OBJECT is currently unused internally by hwloc, but users may for instance use it to provide custom information about host memory accesses performed by GPUs.
    - -
    -
    -
    - - - - - - - -
    -
    -Enumerations | -Functions
    -
    Managing memory attributes
    -
    -
    - - - - -

    -Enumerations

    enum  hwloc_memattr_flag_e { HWLOC_MEMATTR_FLAG_HIGHER_FIRST = (1UL<<0) -, HWLOC_MEMATTR_FLAG_LOWER_FIRST = (1UL<<1) -, HWLOC_MEMATTR_FLAG_NEED_INITIATOR = (1UL<<2) - }
     
    - - - - - - - - - - - - - -

    -Functions

    int hwloc_memattr_get_name (hwloc_topology_t topology, hwloc_memattr_id_t attribute, const char **name)
     
    int hwloc_memattr_get_flags (hwloc_topology_t topology, hwloc_memattr_id_t attribute, unsigned long *flags)
     
    int hwloc_memattr_register (hwloc_topology_t topology, const char *name, unsigned long flags, hwloc_memattr_id_t *id)
     
    int hwloc_memattr_set_value (hwloc_topology_t topology, hwloc_memattr_id_t attribute, hwloc_obj_t target_node, struct hwloc_location *initiator, unsigned long flags, hwloc_uint64_t value)
     
    int hwloc_memattr_get_targets (hwloc_topology_t topology, hwloc_memattr_id_t attribute, struct hwloc_location *initiator, unsigned long flags, unsigned *nr, hwloc_obj_t *targets, hwloc_uint64_t *values)
     
    int hwloc_memattr_get_initiators (hwloc_topology_t topology, hwloc_memattr_id_t attribute, hwloc_obj_t target_node, unsigned long flags, unsigned *nr, struct hwloc_location *initiators, hwloc_uint64_t *values)
     
    -

    Detailed Description

    -

    Enumeration Type Documentation

    - -

    ◆ hwloc_memattr_flag_e

    - -
    -
    - - - - -
    enum hwloc_memattr_flag_e
    -
    - -

    Memory attribute flags. Given to hwloc_memattr_register() and returned by hwloc_memattr_get_flags().

    - - - - -
    Enumerator
    HWLOC_MEMATTR_FLAG_HIGHER_FIRST 

    The best nodes for this memory attribute are those with the higher values. For instance Bandwidth.

    -
    HWLOC_MEMATTR_FLAG_LOWER_FIRST 

    The best nodes for this memory attribute are those with the lower values. For instance Latency.

    -
    HWLOC_MEMATTR_FLAG_NEED_INITIATOR 

    The value returned for this memory attribute depends on the given initiator. For instance Bandwidth and Latency, but not Capacity.

    -
    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_memattr_get_flags()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_memattr_get_flags (hwloc_topology_t topology,
    hwloc_memattr_id_t attribute,
    unsigned long * flags 
    )
    -
    - -

    Return the flags of the given attribute.

    -

    Flags are a OR'ed set of hwloc_memattr_flag_e.

    -
    Returns
    0 on success.
    -
    --1 with errno set to EINVAL if the attribute does not exist.
    - -
    -
    - -

    ◆ hwloc_memattr_get_initiators()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_memattr_get_initiators (hwloc_topology_t topology,
    hwloc_memattr_id_t attribute,
    hwloc_obj_t target_node,
    unsigned long flags,
    unsigned * nr,
    struct hwloc_location * initiators,
    hwloc_uint64_t * values 
    )
    -
    - -

    Return the initiators that have values for a given attribute for a specific target NUMA node.

    -

    Return initiators for the given attribute and target node in the initiators array. If values is not NULL, the corresponding attribute values are stored in the array it points to.

    -

    On input, nr points to the number of initiators that may be stored in the array initiators (and values). On output, nr points to the number of initiators (and values) that were actually found, even if some of them couldn't be stored in the array. Initiators that couldn't be stored are ignored, but the function still returns success (0). The caller may find out by comparing the value pointed by nr before and after the function call.

    -

    The returned initiators should not be modified or freed, they belong to the topology.

    -

    flags must be 0 for now.

    -

    If the attribute does not relate to a specific initiator (it does not have the flag HWLOC_MEMATTR_FLAG_NEED_INITIATOR), no initiator is returned.

    -
    Returns
    0 on success or -1 on error.
    -
    Note
    This function is meant for tools and debugging (listing internal information) rather than for application queries. Applications should rather select useful NUMA nodes with hwloc_get_local_numanode_objs() and then look at their attribute values for some relevant initiators.
    - -
    -
    - -

    ◆ hwloc_memattr_get_name()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_memattr_get_name (hwloc_topology_t topology,
    hwloc_memattr_id_t attribute,
    const char ** name 
    )
    -
    - -

    Return the name of a memory attribute.

    -
    Returns
    0 on success.
    -
    --1 with errno set to EINVAL if the attribute does not exist.
    - -
    -
    - -

    ◆ hwloc_memattr_get_targets()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_memattr_get_targets (hwloc_topology_t topology,
    hwloc_memattr_id_t attribute,
    struct hwloc_location * initiator,
    unsigned long flags,
    unsigned * nr,
    hwloc_obj_t * targets,
    hwloc_uint64_t * values 
    )
    -
    - -

    Return the target NUMA nodes that have some values for a given attribute.

    -

    Return targets for the given attribute in the targets array (for the given initiator if any). If values is not NULL, the corresponding attribute values are stored in the array it points to.

    -

    On input, nr points to the number of targets that may be stored in the array targets (and values). On output, nr points to the number of targets (and values) that were actually found, even if some of them couldn't be stored in the array. Targets that couldn't be stored are ignored, but the function still returns success (0). The caller may find out by comparing the value pointed by nr before and after the function call.

    -

    The returned targets should not be modified or freed, they belong to the topology.

    -

    Argument initiator is ignored if the attribute does not relate to a specific initiator (it does not have the flag HWLOC_MEMATTR_FLAG_NEED_INITIATOR). Otherwise initiator may be non NULL to report only targets that have a value for that initiator.

    -

    flags must be 0 for now.

    -
    Note
    This function is meant for tools and debugging (listing internal information) rather than for application queries. Applications should rather select useful NUMA nodes with hwloc_get_local_numanode_objs() and then look at their attribute values.
    -
    Returns
    0 on success or -1 on error.
    -
    Note
    The initiator initiator should be of type HWLOC_LOCATION_TYPE_CPUSET when referring to accesses performed by CPU cores. HWLOC_LOCATION_TYPE_OBJECT is currently unused internally by hwloc, but users may for instance use it to provide custom information about host memory accesses performed by GPUs.
    - -
    -
    - -

    ◆ hwloc_memattr_register()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_memattr_register (hwloc_topology_t topology,
    const char * name,
    unsigned long flags,
    hwloc_memattr_id_t * id 
    )
    -
    - -

    Register a new memory attribute.

    -

    Add a specific memory attribute that is not defined in hwloc_memattr_id_e. Flags are a OR'ed set of hwloc_memattr_flag_e. It must contain at least one of HWLOC_MEMATTR_FLAG_HIGHER_FIRST or HWLOC_MEMATTR_FLAG_LOWER_FIRST.

    -
    Returns
    0 on success.
    -
    --1 with errno set to EBUSY if another attribute already uses this name.
    - -
    -
    - -

    ◆ hwloc_memattr_set_value()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_memattr_set_value (hwloc_topology_t topology,
    hwloc_memattr_id_t attribute,
    hwloc_obj_t target_node,
    struct hwloc_location * initiator,
    unsigned long flags,
    hwloc_uint64_t value 
    )
    -
    - -

    Set an attribute value for a specific target NUMA node.

    -

    If the attribute does not relate to a specific initiator (it does not have the flag HWLOC_MEMATTR_FLAG_NEED_INITIATOR), location initiator is ignored and may be NULL.

    -

    The initiator will be copied into the topology, the caller should free anything allocated to store the initiator, for instance the cpuset.

    -

    flags must be 0 for now.

    -
    Note
    The initiator initiator should be of type HWLOC_LOCATION_TYPE_CPUSET when referring to accesses performed by CPU cores. HWLOC_LOCATION_TYPE_OBJECT is currently unused internally by hwloc, but users may for instance use it to provide custom information about host memory accesses performed by GPUs.
    -
    Returns
    0 on success or -1 on error.
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    Kinds of CPU cores
    -
    -
    - - - - - - - - - - -

    -Functions

    int hwloc_cpukinds_get_nr (hwloc_topology_t topology, unsigned long flags)
     
    int hwloc_cpukinds_get_by_cpuset (hwloc_topology_t topology, hwloc_const_bitmap_t cpuset, unsigned long flags)
     
    int hwloc_cpukinds_get_info (hwloc_topology_t topology, unsigned kind_index, hwloc_bitmap_t cpuset, int *efficiency, unsigned *nr_infos, struct hwloc_info_s **infos, unsigned long flags)
     
    int hwloc_cpukinds_register (hwloc_topology_t topology, hwloc_bitmap_t cpuset, int forced_efficiency, unsigned nr_infos, struct hwloc_info_s *infos, unsigned long flags)
     
    -

    Detailed Description

    -

    Platforms with heterogeneous CPUs may have some cores with different features or frequencies. This API exposes identical PUs in sets called CPU kinds. Each PU of the topology may only be in a single kind.

    -

    The number of kinds may be obtained with hwloc_cpukinds_get_nr(). If the platform is homogeneous, there may be a single kind with all PUs. If the platform or operating system does not expose any information about CPU cores, there may be no kind at all.

    -

    The index of the kind that describes a given CPU set (if any, and not partially) may be obtained with hwloc_cpukinds_get_by_cpuset().

    -

    From the index of a kind, it is possible to retrieve information with hwloc_cpukinds_get_info(): an abstracted efficiency value, and an array of info attributes (for instance the "CoreType" and "FrequencyMaxMHz", see CPU Kinds).

    -

    A higher efficiency value means greater intrinsic performance (and possibly less performance/power efficiency). Kinds with lower efficiency values are ranked first: Passing 0 as kind_index to hwloc_cpukinds_get_info() will return information about the CPU kind with lower performance but higher energy-efficiency. Higher kind_index values would rather return information about power-hungry high-performance cores.

    -

    When available, efficiency values are gathered from the operating system. If so, cpukind_efficiency is set in the struct hwloc_topology_discovery_support array. This is currently available on Windows 10, Mac OS X (Darwin), and on some Linux platforms where core "capacity" is exposed in sysfs.

    -

    If the operating system does not expose core efficiencies natively, hwloc tries to compute efficiencies by comparing CPU kinds using frequencies (on ARM), or core types and frequencies (on other architectures). The environment variable HWLOC_CPUKINDS_RANKING may be used to change this heuristics, see Environment Variables.

    -

    If hwloc fails to rank any kind, for instance because the operating system does not expose efficiencies and core frequencies, all kinds will have an unknown efficiency (-1), and they are not indexed/ordered in any specific way.

    -

    Function Documentation

    - -

    ◆ hwloc_cpukinds_get_by_cpuset()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_cpukinds_get_by_cpuset (hwloc_topology_t topology,
    hwloc_const_bitmap_t cpuset,
    unsigned long flags 
    )
    -
    - -

    Get the index of the CPU kind that contains CPUs listed in cpuset.

    -

    flags must be 0 for now.

    -
    Returns
    The index of the CPU kind (positive integer or 0) on success.
    -
    --1 with errno set to EXDEV if cpuset is only partially included in the some kind.
    -
    --1 with errno set to ENOENT if cpuset is not included in any kind, even partially.
    -
    --1 with errno set to EINVAL if parameters are invalid.
    - -
    -
    - -

    ◆ hwloc_cpukinds_get_info()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_cpukinds_get_info (hwloc_topology_t topology,
    unsigned kind_index,
    hwloc_bitmap_t cpuset,
    int * efficiency,
    unsigned * nr_infos,
    struct hwloc_info_s ** infos,
    unsigned long flags 
    )
    -
    - -

    Get the CPU set and infos about a CPU kind in the topology.

    -

    kind_index identifies one kind of CPU between 0 and the number of kinds returned by hwloc_cpukinds_get_nr() minus 1.

    -

    If not NULL, the bitmap cpuset will be filled with the set of PUs of this kind.

    -

    The integer pointed by efficiency, if not NULL will, be filled with the ranking of this kind of CPU in term of efficiency (see above). It ranges from 0 to the number of kinds (as reported by hwloc_cpukinds_get_nr()) minus 1.

    -

    Kinds with lower efficiency are reported first.

    -

    If there is a single kind in the topology, its efficiency 0. If the efficiency of some kinds of cores is unknown, the efficiency of all kinds is set to -1, and kinds are reported in no specific order.

    -

    The array of info attributes (for instance the "CoreType", "FrequencyMaxMHz" or "FrequencyBaseMHz", see CPU Kinds) and its length are returned in infos or nr_infos. The array belongs to the topology, it should not be freed or modified.

    -

    If nr_infos or infos is NULL, no info is returned.

    -

    flags must be 0 for now.

    -
    Returns
    0 on success.
    -
    --1 with errno set to ENOENT if kind_index does not match any CPU kind.
    -
    --1 with errno set to EINVAL if parameters are invalid.
    - -
    -
    - -

    ◆ hwloc_cpukinds_get_nr()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_cpukinds_get_nr (hwloc_topology_t topology,
    unsigned long flags 
    )
    -
    - -

    Get the number of different kinds of CPU cores in the topology.

    -

    flags must be 0 for now.

    -
    Returns
    The number of CPU kinds (positive integer) on success.
    -
    -0 if no information about kinds was found.
    -
    --1 with errno set to EINVAL if flags is invalid.
    - -
    -
    - -

    ◆ hwloc_cpukinds_register()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_cpukinds_register (hwloc_topology_t topology,
    hwloc_bitmap_t cpuset,
    int forced_efficiency,
    unsigned nr_infos,
    struct hwloc_info_s * infos,
    unsigned long flags 
    )
    -
    - -

    Register a kind of CPU in the topology.

    -

    Mark the PUs listed in cpuset as being of the same kind with respect to the given attributes.

    -

    forced_efficiency should be -1 if unknown. Otherwise it is an abstracted efficiency value to enforce the ranking of all kinds if all of them have valid (and different) efficiencies.

    -

    The array infos of size nr_infos may be used to provide info names and values describing this kind of PUs.

    -

    flags must be 0 for now.

    -

    Parameters cpuset and infos will be duplicated internally, the caller is responsible for freeing them.

    -

    If cpuset overlaps with some existing kinds, those might get modified or split. For instance if existing kind A contains PUs 0 and 1, and one registers another kind for PU 1 and 2, there will be 3 resulting kinds: existing kind A is restricted to only PU 0; new kind B contains only PU 1 and combines information from A and from the newly-registered kind; new kind C contains only PU 2 and only gets information from the newly-registered kind.

    -
    Note
    The efficiency forced_efficiency provided to this function may be different from the one reported later by hwloc_cpukinds_get_info() because hwloc will scale efficiency values down to between 0 and the number of kinds minus 1.
    -
    Returns
    0 on success.
    -
    --1 with errno set to EINVAL if some parameters are invalid, for instance if cpuset is NULL or empty.
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    Linux-specific helpers
    -
    -
    - - - - - - - - - - -

    -Functions

    int hwloc_linux_set_tid_cpubind (hwloc_topology_t topology, pid_t tid, hwloc_const_cpuset_t set)
     
    int hwloc_linux_get_tid_cpubind (hwloc_topology_t topology, pid_t tid, hwloc_cpuset_t set)
     
    int hwloc_linux_get_tid_last_cpu_location (hwloc_topology_t topology, pid_t tid, hwloc_bitmap_t set)
     
    int hwloc_linux_read_path_as_cpumask (const char *path, hwloc_bitmap_t set)
     
    -

    Detailed Description

    -

    This includes helpers for manipulating Linux kernel cpumap files, and hwloc equivalents of the Linux sched_setaffinity and sched_getaffinity system calls.

    -

    Function Documentation

    - -

    ◆ hwloc_linux_get_tid_cpubind()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_linux_get_tid_cpubind (hwloc_topology_t topology,
    pid_t tid,
    hwloc_cpuset_t set 
    )
    -
    - -

    Get the current binding of thread tid.

    -

    The CPU-set set (previously allocated by the caller) is filled with the list of PUs which the thread was last bound to.

    -

    The behavior is exactly the same as the Linux sched_getaffinity system call, but uses a hwloc cpuset.

    -
    Returns
    0 on success, -1 on error.
    -
    Note
    This is equivalent to calling hwloc_get_proc_cpubind() with HWLOC_CPUBIND_THREAD as flags.
    - -
    -
    - -

    ◆ hwloc_linux_get_tid_last_cpu_location()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_linux_get_tid_last_cpu_location (hwloc_topology_t topology,
    pid_t tid,
    hwloc_bitmap_t set 
    )
    -
    - -

    Get the last physical CPU where thread tid ran.

    -

    The CPU-set set (previously allocated by the caller) is filled with the PU which the thread last ran on.

    -
    Returns
    0 on success, -1 on error.
    -
    Note
    This is equivalent to calling hwloc_get_proc_last_cpu_location() with HWLOC_CPUBIND_THREAD as flags.
    - -
    -
    - -

    ◆ hwloc_linux_read_path_as_cpumask()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_linux_read_path_as_cpumask (const char * path,
    hwloc_bitmap_t set 
    )
    -
    - -

    Convert a linux kernel cpumask file path into a hwloc bitmap set.

    -

    Might be used when reading CPU set from sysfs attributes such as topology and caches for processors, or local_cpus for devices.

    -
    Returns
    0 on success, -1 on error.
    -
    Note
    This function ignores the HWLOC_FSROOT environment variable.
    - -
    -
    - -

    ◆ hwloc_linux_set_tid_cpubind()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_linux_set_tid_cpubind (hwloc_topology_t topology,
    pid_t tid,
    hwloc_const_cpuset_t set 
    )
    -
    - -

    Bind a thread tid on cpus given in cpuset set.

    -

    The behavior is exactly the same as the Linux sched_setaffinity system call, but uses a hwloc cpuset.

    -
    Returns
    0 on success, -1 on error.
    -
    Note
    This is equivalent to calling hwloc_set_proc_cpubind() with HWLOC_CPUBIND_THREAD as flags.
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    Interoperability with Linux libnuma unsigned long masks
    -
    -
    - - - - - - - - - - -

    -Functions

    static int hwloc_cpuset_to_linux_libnuma_ulongs (hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, unsigned long *mask, unsigned long *maxnode)
     
    static int hwloc_nodeset_to_linux_libnuma_ulongs (hwloc_topology_t topology, hwloc_const_nodeset_t nodeset, unsigned long *mask, unsigned long *maxnode)
     
    static int hwloc_cpuset_from_linux_libnuma_ulongs (hwloc_topology_t topology, hwloc_cpuset_t cpuset, const unsigned long *mask, unsigned long maxnode)
     
    static int hwloc_nodeset_from_linux_libnuma_ulongs (hwloc_topology_t topology, hwloc_nodeset_t nodeset, const unsigned long *mask, unsigned long maxnode)
     
    -

    Detailed Description

    -

    This interface helps converting between Linux libnuma unsigned long masks and hwloc cpusets and nodesets.

    -
    Note
    Topology topology must match the current machine.
    -
    -The behavior of libnuma is undefined if the kernel is not NUMA-aware. (when CONFIG_NUMA is not set in the kernel configuration). This helper and libnuma may thus not be strictly compatible in this case, which may be detected by checking whether numa_available() returns -1.
    -

    Function Documentation

    - -

    ◆ hwloc_cpuset_from_linux_libnuma_ulongs()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_cpuset_from_linux_libnuma_ulongs (hwloc_topology_t topology,
    hwloc_cpuset_t cpuset,
    const unsigned long * mask,
    unsigned long maxnode 
    )
    -     		-inlinestatic
    -
    - -

    Convert the array of unsigned long mask into hwloc CPU set.

    -

    mask is a array of unsigned long that will be read. maxnode contains the maximal node number that may be read in mask.

    -

    This function may be used after calling get_mempolicy or any other function that takes an array of unsigned long as output parameter (and possibly a maximal node number as input parameter).

    -
    Returns
    0 on success.
    -
    --1 on error, for instance if failing an internal reallocation.
    - -
    -
    - -

    ◆ hwloc_cpuset_to_linux_libnuma_ulongs()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_cpuset_to_linux_libnuma_ulongs (hwloc_topology_t topology,
    hwloc_const_cpuset_t cpuset,
    unsigned long * mask,
    unsigned long * maxnode 
    )
    -     		-inlinestatic
    -
    - -

    Convert hwloc CPU set cpuset into the array of unsigned long mask.

    -

    mask is the array of unsigned long that will be filled. maxnode contains the maximal node number that may be stored in mask. maxnode will be set to the maximal node number that was found, plus one.

    -

    This function may be used before calling set_mempolicy, mbind, migrate_pages or any other function that takes an array of unsigned long and a maximal node number as input parameter.

    -
    Returns
    0.
    - -
    -
    - -

    ◆ hwloc_nodeset_from_linux_libnuma_ulongs()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_nodeset_from_linux_libnuma_ulongs (hwloc_topology_t topology,
    hwloc_nodeset_t nodeset,
    const unsigned long * mask,
    unsigned long maxnode 
    )
    -     		-inlinestatic
    -
    - -

    Convert the array of unsigned long mask into hwloc NUMA node set.

    -

    mask is a array of unsigned long that will be read. maxnode contains the maximal node number that may be read in mask.

    -

    This function may be used after calling get_mempolicy or any other function that takes an array of unsigned long as output parameter (and possibly a maximal node number as input parameter).

    -
    Returns
    0 on success.
    -
    --1 with errno set to ENOMEM if some internal reallocation failed.
    - -
    -
    - -

    ◆ hwloc_nodeset_to_linux_libnuma_ulongs()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_nodeset_to_linux_libnuma_ulongs (hwloc_topology_t topology,
    hwloc_const_nodeset_t nodeset,
    unsigned long * mask,
    unsigned long * maxnode 
    )
    -     		-inlinestatic
    -
    - -

    Convert hwloc NUMA node set nodeset into the array of unsigned long mask.

    -

    mask is the array of unsigned long that will be filled. maxnode contains the maximal node number that may be stored in mask. maxnode will be set to the maximal node number that was found, plus one.

    -

    This function may be used before calling set_mempolicy, mbind, migrate_pages or any other function that takes an array of unsigned long and a maximal node number as input parameter.

    -
    Returns
    0.
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    Interoperability with Linux libnuma bitmask
    -
    -
    - - - - - - - - - - -

    -Functions

    static struct bitmask * hwloc_cpuset_to_linux_libnuma_bitmask (hwloc_topology_t topology, hwloc_const_cpuset_t cpuset)
     
    static struct bitmask * hwloc_nodeset_to_linux_libnuma_bitmask (hwloc_topology_t topology, hwloc_const_nodeset_t nodeset)
     
    static int hwloc_cpuset_from_linux_libnuma_bitmask (hwloc_topology_t topology, hwloc_cpuset_t cpuset, const struct bitmask *bitmask)
     
    static int hwloc_nodeset_from_linux_libnuma_bitmask (hwloc_topology_t topology, hwloc_nodeset_t nodeset, const struct bitmask *bitmask)
     
    -

    Detailed Description

    -

    This interface helps converting between Linux libnuma bitmasks and hwloc cpusets and nodesets.

    -
    Note
    Topology topology must match the current machine.
    -
    -The behavior of libnuma is undefined if the kernel is not NUMA-aware. (when CONFIG_NUMA is not set in the kernel configuration). This helper and libnuma may thus not be strictly compatible in this case, which may be detected by checking whether numa_available() returns -1.
    -

    Function Documentation

    - -

    ◆ hwloc_cpuset_from_linux_libnuma_bitmask()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_cpuset_from_linux_libnuma_bitmask (hwloc_topology_t topology,
    hwloc_cpuset_t cpuset,
    const struct bitmask * bitmask 
    )
    -     		-inlinestatic
    -
    - -

    Convert libnuma bitmask bitmask into hwloc CPU set cpuset.

    -

    This function may be used after calling many numa_ functions that use a struct bitmask as an output parameter.

    -
    Returns
    0 on success.
    -
    --1 with errno set to ENOMEM if some internal reallocation failed.
    - -
    -
    - -

    ◆ hwloc_cpuset_to_linux_libnuma_bitmask()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static struct bitmask * hwloc_cpuset_to_linux_libnuma_bitmask (hwloc_topology_t topology,
    hwloc_const_cpuset_t cpuset 
    )
    -     		-inlinestatic
    -
    - -

    Convert hwloc CPU set cpuset into the returned libnuma bitmask.

    -

    The returned bitmask should later be freed with numa_bitmask_free.

    -

    This function may be used before calling many numa_ functions that use a struct bitmask as an input parameter.

    -
    Returns
    newly allocated struct bitmask, or NULL on error.
    - -
    -
    - -

    ◆ hwloc_nodeset_from_linux_libnuma_bitmask()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_nodeset_from_linux_libnuma_bitmask (hwloc_topology_t topology,
    hwloc_nodeset_t nodeset,
    const struct bitmask * bitmask 
    )
    -     		-inlinestatic
    -
    - -

    Convert libnuma bitmask bitmask into hwloc NUMA node set nodeset.

    -

    This function may be used after calling many numa_ functions that use a struct bitmask as an output parameter.

    -
    Returns
    0 on success.
    -
    --1 with errno set to ENOMEM if some internal reallocation failed.
    - -
    -
    - -

    ◆ hwloc_nodeset_to_linux_libnuma_bitmask()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static struct bitmask * hwloc_nodeset_to_linux_libnuma_bitmask (hwloc_topology_t topology,
    hwloc_const_nodeset_t nodeset 
    )
    -     		-inlinestatic
    -
    - -

    Convert hwloc NUMA node set nodeset into the returned libnuma bitmask.

    -

    The returned bitmask should later be freed with numa_bitmask_free.

    -

    This function may be used before calling many numa_ functions that use a struct bitmask as an input parameter.

    -
    Returns
    newly allocated struct bitmask, or NULL on error.
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    Windows-specific helpers
    -
    -
    - - - - - - -

    -Functions

    int hwloc_windows_get_nr_processor_groups (hwloc_topology_t topology, unsigned long flags)
     
    int hwloc_windows_get_processor_group_cpuset (hwloc_topology_t topology, unsigned pg_index, hwloc_cpuset_t cpuset, unsigned long flags)
     
    -

    Detailed Description

    -

    These functions query Windows processor groups. These groups partition the operating system into virtual sets of up to 64 neighbor PUs. Threads and processes may only be bound inside a single group. Although Windows processor groups may be exposed in the hwloc hierarchy as hwloc Groups, they are also often merged into existing hwloc objects such as NUMA nodes or Packages. This API provides explicit information about Windows processor groups so that applications know whether binding to a large set of PUs may fail because it spans over multiple Windows processor groups.

    -

    Function Documentation

    - -

    ◆ hwloc_windows_get_nr_processor_groups()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_windows_get_nr_processor_groups (hwloc_topology_t topology,
    unsigned long flags 
    )
    -
    - -

    Get the number of Windows processor groups.

    -

    flags must be 0 for now.

    -
    Returns
    at least 1 on success.
    -
    --1 on error, for instance if the topology does not match the current system (e.g. loaded from another machine through XML).
    - -
    -
    - -

    ◆ hwloc_windows_get_processor_group_cpuset()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_windows_get_processor_group_cpuset (hwloc_topology_t topology,
    unsigned pg_index,
    hwloc_cpuset_t cpuset,
    unsigned long flags 
    )
    -
    - -

    Get the CPU-set of a Windows processor group.

    -

    Get the set of PU included in the processor group specified by pg_index. pg_index must be between 0 and the value returned by hwloc_windows_get_nr_processor_groups() minus 1.

    -

    flags must be 0 for now.

    -
    Returns
    0 on success.
    -
    --1 on error, for instance if pg_index is invalid, or if the topology does not match the current system (e.g. loaded from another machine through XML).
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    Interoperability with glibc sched affinity
    -
    -
    - - - - - - -

    -Functions

    static int hwloc_cpuset_to_glibc_sched_affinity (hwloc_topology_t topology, hwloc_const_cpuset_t hwlocset, cpu_set_t *schedset, size_t schedsetsize)
     
    static int hwloc_cpuset_from_glibc_sched_affinity (hwloc_topology_t topology, hwloc_cpuset_t hwlocset, const cpu_set_t *schedset, size_t schedsetsize)
     
    -

    Detailed Description

    -

    This interface offers ways to convert between hwloc cpusets and glibc cpusets such as those manipulated by sched_getaffinity() or pthread_attr_setaffinity_np().

    -
    Note
    Topology topology must match the current machine.
    -

    Function Documentation

    - -

    ◆ hwloc_cpuset_from_glibc_sched_affinity()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_cpuset_from_glibc_sched_affinity (hwloc_topology_t topology,
    hwloc_cpuset_t hwlocset,
    const cpu_set_t * schedset,
    size_t schedsetsize 
    )
    -     		-inlinestatic
    -
    - -

    Convert glibc sched affinity CPU set schedset into hwloc CPU set.

    -

    This function may be used before calling sched_setaffinity or any other function that takes a cpu_set_t as input parameter.

    -

    schedsetsize should be sizeof(cpu_set_t) unless schedset was dynamically allocated with CPU_ALLOC

    -
    Returns
    0 on success.
    -
    --1 with errno set to ENOMEM if some internal reallocation failed.
    - -
    -
    - -

    ◆ hwloc_cpuset_to_glibc_sched_affinity()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_cpuset_to_glibc_sched_affinity (hwloc_topology_t topology,
    hwloc_const_cpuset_t hwlocset,
    cpu_set_t * schedset,
    size_t schedsetsize 
    )
    -     		-inlinestatic
    -
    - -

    Convert hwloc CPU set toposet into glibc sched affinity CPU set schedset.

    -

    This function may be used before calling sched_setaffinity or any other function that takes a cpu_set_t as input parameter.

    -

    schedsetsize should be sizeof(cpu_set_t) unless schedset was dynamically allocated with CPU_ALLOC

    -
    Returns
    0.
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    Interoperability with OpenCL
    -
    -
    - - - - - - - - - - -

    -Functions

    static int hwloc_opencl_get_device_pci_busid (cl_device_id device, unsigned *domain, unsigned *bus, unsigned *dev, unsigned *func)
     
    static int hwloc_opencl_get_device_cpuset (hwloc_topology_t topology, cl_device_id device, hwloc_cpuset_t set)
     
    static hwloc_obj_t hwloc_opencl_get_device_osdev_by_index (hwloc_topology_t topology, unsigned platform_index, unsigned device_index)
     
    static hwloc_obj_t hwloc_opencl_get_device_osdev (hwloc_topology_t topology, cl_device_id device)
     
    -

    Detailed Description

    -

    This interface offers ways to retrieve topology information about OpenCL devices.

    -

    Only AMD and NVIDIA OpenCL implementations currently offer useful locality information about their devices.

    -

    Function Documentation

    - -

    ◆ hwloc_opencl_get_device_cpuset()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_opencl_get_device_cpuset (hwloc_topology_t topology,
    cl_device_id device,
    hwloc_cpuset_t set 
    )
    -     		-inlinestatic
    -
    - -

    Get the CPU set of processors that are physically close to OpenCL device device.

    -

    Store in set the CPU-set describing the locality of the OpenCL device device.

    -

    Topology topology and device device must match the local machine. I/O devices detection and the OpenCL component are not needed in the topology.

    -

    The function only returns the locality of the device. If more information about the device is needed, OS objects should be used instead, see hwloc_opencl_get_device_osdev() and hwloc_opencl_get_device_osdev_by_index().

    -

    This function is currently only implemented in a meaningful way for Linux with the AMD or NVIDIA OpenCL implementation; other systems will simply get a full cpuset.

    -
    Returns
    0 on success.
    -
    --1 on error, for instance if the device could not be found.
    - -
    -
    - -

    ◆ hwloc_opencl_get_device_osdev()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_opencl_get_device_osdev (hwloc_topology_t topology,
    cl_device_id device 
    )
    -     		-inlinestatic
    -
    - -

    Get the hwloc OS device object corresponding to OpenCL device deviceX.

    -
    Returns
    The hwloc OS device object corresponding to the given OpenCL device device.
    -
    -NULL if none could be found, for instance if required OpenCL attributes are not available.
    -

    This function currently only works on AMD and NVIDIA OpenCL devices that support relevant OpenCL extensions. hwloc_opencl_get_device_osdev_by_index() should be preferred whenever possible, i.e. when platform and device index are known.

    -

    Topology topology and device device must match the local machine. I/O devices detection and the OpenCL component must be enabled in the topology. If not, the locality of the object may still be found using hwloc_opencl_get_device_cpuset().

    -
    Note
    This function cannot work if PCI devices are filtered out.
    -
    -The corresponding hwloc PCI device may be found by looking at the result parent pointer (unless PCI devices are filtered out).
    - -
    -
    - -

    ◆ hwloc_opencl_get_device_osdev_by_index()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_opencl_get_device_osdev_by_index (hwloc_topology_t topology,
    unsigned platform_index,
    unsigned device_index 
    )
    -     		-inlinestatic
    -
    - -

    Get the hwloc OS device object corresponding to the OpenCL device for the given indexes.

    -
    Returns
    The hwloc OS device object describing the OpenCL device whose platform index is platform_index, and whose device index within this platform if device_index.
    -
    -NULL if there is none.
    -

    The topology topology does not necessarily have to match the current machine. For instance the topology may be an XML import of a remote host. I/O devices detection and the OpenCL component must be enabled in the topology.

    -
    Note
    The corresponding PCI device object can be obtained by looking at the OS device parent object (unless PCI devices are filtered out).
    - -
    -
    - -

    ◆ hwloc_opencl_get_device_pci_busid()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_opencl_get_device_pci_busid (cl_device_id device,
    unsigned * domain,
    unsigned * bus,
    unsigned * dev,
    unsigned * func 
    )
    -     		-inlinestatic
    -
    - -

    Return the domain, bus and device IDs of the OpenCL device device.

    -

    Device device must match the local machine.

    -
    Returns
    0 on success.
    -
    --1 on error, for instance if device information could not be found.
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    Interoperability with the CUDA Driver API
    -
    -
    - - - - - - - - - - - - -

    -Functions

    static int hwloc_cuda_get_device_pci_ids (hwloc_topology_t topology, CUdevice cudevice, int *domain, int *bus, int *dev)
     
    static int hwloc_cuda_get_device_cpuset (hwloc_topology_t topology, CUdevice cudevice, hwloc_cpuset_t set)
     
    static hwloc_obj_t hwloc_cuda_get_device_pcidev (hwloc_topology_t topology, CUdevice cudevice)
     
    static hwloc_obj_t hwloc_cuda_get_device_osdev (hwloc_topology_t topology, CUdevice cudevice)
     
    static hwloc_obj_t hwloc_cuda_get_device_osdev_by_index (hwloc_topology_t topology, unsigned idx)
     
    -

    Detailed Description

    -

    This interface offers ways to retrieve topology information about CUDA devices when using the CUDA Driver API.

    -

    Function Documentation

    - -

    ◆ hwloc_cuda_get_device_cpuset()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_cuda_get_device_cpuset (hwloc_topology_t topology,
    CUdevice cudevice,
    hwloc_cpuset_t set 
    )
    -     		-inlinestatic
    -
    - -

    Get the CPU set of processors that are physically close to device cudevice.

    -

    Store in set the CPU-set describing the locality of the CUDA device cudevice.

    -

    Topology topology and device cudevice must match the local machine. I/O devices detection and the CUDA component are not needed in the topology.

    -

    The function only returns the locality of the device. If more information about the device is needed, OS objects should be used instead, see hwloc_cuda_get_device_osdev() and hwloc_cuda_get_device_osdev_by_index().

    -

    This function is currently only implemented in a meaningful way for Linux; other systems will simply get a full cpuset.

    -
    Returns
    0 on success.
    -
    --1 on error, for instance if device information could not be found.
    - -
    -
    - -

    ◆ hwloc_cuda_get_device_osdev()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_cuda_get_device_osdev (hwloc_topology_t topology,
    CUdevice cudevice 
    )
    -     		-inlinestatic
    -
    - -

    Get the hwloc OS device object corresponding to CUDA device cudevice.

    -
    Returns
    The hwloc OS device object that describes the given CUDA device cudevice.
    -
    -NULL if none could be found.
    -

    Topology topology and device cudevice must match the local machine. I/O devices detection and the CUDA component must be enabled in the topology. If not, the locality of the object may still be found using hwloc_cuda_get_device_cpuset().

    -
    Note
    This function cannot work if PCI devices are filtered out.
    -
    -The corresponding hwloc PCI device may be found by looking at the result parent pointer (unless PCI devices are filtered out).
    - -
    -
    - -

    ◆ hwloc_cuda_get_device_osdev_by_index()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_cuda_get_device_osdev_by_index (hwloc_topology_t topology,
    unsigned idx 
    )
    -     		-inlinestatic
    -
    - -

    Get the hwloc OS device object corresponding to the CUDA device whose index is idx.

    -
    Returns
    The hwloc OS device object describing the CUDA device whose index is idx.
    -
    -NULL if none could be found.
    -

    The topology topology does not necessarily have to match the current machine. For instance the topology may be an XML import of a remote host. I/O devices detection and the CUDA component must be enabled in the topology.

    -
    Note
    The corresponding PCI device object can be obtained by looking at the OS device parent object (unless PCI devices are filtered out).
    -
    -This function is identical to hwloc_cudart_get_device_osdev_by_index().
    - -
    -
    - -

    ◆ hwloc_cuda_get_device_pci_ids()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_cuda_get_device_pci_ids (hwloc_topology_t topology,
    CUdevice cudevice,
    int * domain,
    int * bus,
    int * dev 
    )
    -     		-inlinestatic
    -
    - -

    Return the domain, bus and device IDs of the CUDA device cudevice.

    -

    Device cudevice must match the local machine.

    -
    Returns
    0 on success.
    -
    --1 on error, for instance if device information could not be found.
    - -
    -
    - -

    ◆ hwloc_cuda_get_device_pcidev()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_cuda_get_device_pcidev (hwloc_topology_t topology,
    CUdevice cudevice 
    )
    -     		-inlinestatic
    -
    - -

    Get the hwloc PCI device object corresponding to the CUDA device cudevice.

    -
    Returns
    The hwloc PCI device object describing the CUDA device cudevice.
    -
    -NULL if none could be found.
    -

    Topology topology and device cudevice must match the local machine. I/O devices detection must be enabled in topology topology. The CUDA component is not needed in the topology.

    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    Interoperability with the CUDA Runtime API
    -
    -
    - - - - - - - - - - -

    -Functions

    static int hwloc_cudart_get_device_pci_ids (hwloc_topology_t topology, int idx, int *domain, int *bus, int *dev)
     
    static int hwloc_cudart_get_device_cpuset (hwloc_topology_t topology, int idx, hwloc_cpuset_t set)
     
    static hwloc_obj_t hwloc_cudart_get_device_pcidev (hwloc_topology_t topology, int idx)
     
    static hwloc_obj_t hwloc_cudart_get_device_osdev_by_index (hwloc_topology_t topology, unsigned idx)
     
    -

    Detailed Description

    -

    This interface offers ways to retrieve topology information about CUDA devices when using the CUDA Runtime API.

    -

    Function Documentation

    - -

    ◆ hwloc_cudart_get_device_cpuset()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_cudart_get_device_cpuset (hwloc_topology_t topology,
    int idx,
    hwloc_cpuset_t set 
    )
    -     		-inlinestatic
    -
    - -

    Get the CPU set of processors that are physically close to device idx.

    -

    Store in set the CPU-set describing the locality of the CUDA device whose index is idx.

    -

    Topology topology and device idx must match the local machine. I/O devices detection and the CUDA component are not needed in the topology.

    -

    The function only returns the locality of the device. If more information about the device is needed, OS objects should be used instead, see hwloc_cudart_get_device_osdev_by_index().

    -

    This function is currently only implemented in a meaningful way for Linux; other systems will simply get a full cpuset.

    -
    Returns
    0 on success.
    -
    --1 on error, for instance if device information could not be found.
    - -
    -
    - -

    ◆ hwloc_cudart_get_device_osdev_by_index()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_cudart_get_device_osdev_by_index (hwloc_topology_t topology,
    unsigned idx 
    )
    -     		-inlinestatic
    -
    - -

    Get the hwloc OS device object corresponding to the CUDA device whose index is idx.

    -
    Returns
    The hwloc OS device object describing the CUDA device whose index is idx.
    -
    -NULL if none could be found.
    -

    The topology topology does not necessarily have to match the current machine. For instance the topology may be an XML import of a remote host. I/O devices detection and the CUDA component must be enabled in the topology. If not, the locality of the object may still be found using hwloc_cudart_get_device_cpuset().

    -
    Note
    The corresponding PCI device object can be obtained by looking at the OS device parent object (unless PCI devices are filtered out).
    -
    -This function is identical to hwloc_cuda_get_device_osdev_by_index().
    - -
    -
    - -

    ◆ hwloc_cudart_get_device_pci_ids()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_cudart_get_device_pci_ids (hwloc_topology_t topology,
    int idx,
    int * domain,
    int * bus,
    int * dev 
    )
    -     		-inlinestatic
    -
    - -

    Return the domain, bus and device IDs of the CUDA device whose index is idx.

    -

    Device index idx must match the local machine.

    -
    Returns
    0 on success.
    -
    --1 on error, for instance if device information could not be found.
    - -
    -
    - -

    ◆ hwloc_cudart_get_device_pcidev()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_cudart_get_device_pcidev (hwloc_topology_t topology,
    int idx 
    )
    -     		-inlinestatic
    -
    - -

    Get the hwloc PCI device object corresponding to the CUDA device whose index is idx.

    -
    Returns
    The hwloc PCI device object describing the CUDA device whose index is idx.
    -
    -NULL if none could be found.
    -

    Topology topology and device idx must match the local machine. I/O devices detection must be enabled in topology topology. The CUDA component is not needed in the topology.

    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    Interoperability with the NVIDIA Management Library
    -
    -
    - - - - - - - - -

    -Functions

    static int hwloc_nvml_get_device_cpuset (hwloc_topology_t topology, nvmlDevice_t device, hwloc_cpuset_t set)
     
    static hwloc_obj_t hwloc_nvml_get_device_osdev_by_index (hwloc_topology_t topology, unsigned idx)
     
    static hwloc_obj_t hwloc_nvml_get_device_osdev (hwloc_topology_t topology, nvmlDevice_t device)
     
    -

    Detailed Description

    -

    This interface offers ways to retrieve topology information about devices managed by the NVIDIA Management Library (NVML).

    -

    Function Documentation

    - -

    ◆ hwloc_nvml_get_device_cpuset()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_nvml_get_device_cpuset (hwloc_topology_t topology,
    nvmlDevice_t device,
    hwloc_cpuset_t set 
    )
    -     		-inlinestatic
    -
    - -

    Get the CPU set of processors that are physically close to NVML device device.

    -

    Store in set the CPU-set describing the locality of the NVML device device.

    -

    Topology topology and device device must match the local machine. I/O devices detection and the NVML component are not needed in the topology.

    -

    The function only returns the locality of the device. If more information about the device is needed, OS objects should be used instead, see hwloc_nvml_get_device_osdev() and hwloc_nvml_get_device_osdev_by_index().

    -

    This function is currently only implemented in a meaningful way for Linux; other systems will simply get a full cpuset.

    -
    Returns
    0 on success.
    -
    --1 on error, for instance if device information could not be found.
    - -
    -
    - -

    ◆ hwloc_nvml_get_device_osdev()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_nvml_get_device_osdev (hwloc_topology_t topology,
    nvmlDevice_t device 
    )
    -     		-inlinestatic
    -
    - -

    Get the hwloc OS device object corresponding to NVML device device.

    -
    Returns
    The hwloc OS device object that describes the given NVML device device.
    -
    -NULL if none could be found.
    -

    Topology topology and device device must match the local machine. I/O devices detection and the NVML component must be enabled in the topology. If not, the locality of the object may still be found using hwloc_nvml_get_device_cpuset().

    -
    Note
    The corresponding hwloc PCI device may be found by looking at the result parent pointer (unless PCI devices are filtered out).
    - -
    -
    - -

    ◆ hwloc_nvml_get_device_osdev_by_index()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_nvml_get_device_osdev_by_index (hwloc_topology_t topology,
    unsigned idx 
    )
    -     		-inlinestatic
    -
    - -

    Get the hwloc OS device object corresponding to the NVML device whose index is idx.

    -
    Returns
    The hwloc OS device object describing the NVML device whose index is idx.
    -
    -NULL if none could be found.
    -

    The topology topology does not necessarily have to match the current machine. For instance the topology may be an XML import of a remote host. I/O devices detection and the NVML component must be enabled in the topology.

    -
    Note
    The corresponding PCI device object can be obtained by looking at the OS device parent object (unless PCI devices are filtered out).
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    Interoperability with the ROCm SMI Management Library
    -
    -
    - - - - - - - - -

    -Functions

    static int hwloc_rsmi_get_device_cpuset (hwloc_topology_t topology, uint32_t dv_ind, hwloc_cpuset_t set)
     
    static hwloc_obj_t hwloc_rsmi_get_device_osdev_by_index (hwloc_topology_t topology, uint32_t dv_ind)
     
    static hwloc_obj_t hwloc_rsmi_get_device_osdev (hwloc_topology_t topology, uint32_t dv_ind)
     
    -

    Detailed Description

    -

    This interface offers ways to retrieve topology information about devices managed by the ROCm SMI Management Library.

    -

    Function Documentation

    - -

    ◆ hwloc_rsmi_get_device_cpuset()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_rsmi_get_device_cpuset (hwloc_topology_t topology,
    uint32_t dv_ind,
    hwloc_cpuset_t set 
    )
    -     		-inlinestatic
    -
    - -

    Get the CPU set of logical processors that are physically close to AMD GPU device whose index is dv_ind.

    -

    Store in set the CPU-set describing the locality of the AMD GPU device whose index is dv_ind.

    -

    Topology topology and device dv_ind must match the local machine. I/O devices detection and the ROCm SMI component are not needed in the topology.

    -

    The function only returns the locality of the device. If more information about the device is needed, OS objects should be used instead, see hwloc_rsmi_get_device_osdev() and hwloc_rsmi_get_device_osdev_by_index().

    -

    This function is currently only implemented in a meaningful way for Linux; other systems will simply get a full cpuset.

    -
    Returns
    0 on success.
    -
    --1 on error, for instance if device information could not be found.
    - -
    -
    - -

    ◆ hwloc_rsmi_get_device_osdev()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_rsmi_get_device_osdev (hwloc_topology_t topology,
    uint32_t dv_ind 
    )
    -     		-inlinestatic
    -
    - -

    Get the hwloc OS device object corresponding to AMD GPU device, whose index is dv_ind.

    -
    Returns
    The hwloc OS device object that describes the given AMD GPU, whose index is dv_ind.
    -
    -NULL if none could be found.
    -

    Topology topology and device dv_ind must match the local machine. I/O devices detection and the ROCm SMI component must be enabled in the topology. If not, the locality of the object may still be found using hwloc_rsmi_get_device_cpuset().

    -
    Note
    The corresponding hwloc PCI device may be found by looking at the result parent pointer (unless PCI devices are filtered out).
    - -
    -
    - -

    ◆ hwloc_rsmi_get_device_osdev_by_index()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_rsmi_get_device_osdev_by_index (hwloc_topology_t topology,
    uint32_t dv_ind 
    )
    -     		-inlinestatic
    -
    - -

    Get the hwloc OS device object corresponding to the AMD GPU device whose index is dv_ind.

    -
    Returns
    The hwloc OS device object describing the AMD GPU device whose index is dv_ind.
    -
    -NULL if none could be found.
    -

    The topology topology does not necessarily have to match the current machine. For instance the topology may be an XML import of a remote host. I/O devices detection and the ROCm SMI component must be enabled in the topology.

    -
    Note
    The corresponding PCI device object can be obtained by looking at the OS device parent object (unless PCI devices are filtered out).
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    Interoperability with the oneAPI Level Zero interface.
    -
    -
    - - - - - - -

    -Functions

    static int hwloc_levelzero_get_device_cpuset (hwloc_topology_t topology, ze_device_handle_t device, hwloc_cpuset_t set)
     
    static hwloc_obj_t hwloc_levelzero_get_device_osdev (hwloc_topology_t topology, ze_device_handle_t device)
     
    -

    Detailed Description

    -

    This interface offers ways to retrieve topology information about devices managed by the Level Zero API.

    -

    Function Documentation

    - -

    ◆ hwloc_levelzero_get_device_cpuset()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_levelzero_get_device_cpuset (hwloc_topology_t topology,
    ze_device_handle_t device,
    hwloc_cpuset_t set 
    )
    -     		-inlinestatic
    -
    - -

    Get the CPU set of logical processors that are physically close to the Level Zero device device.

    -

    Store in set the CPU-set describing the locality of the Level Zero device device.

    -

    Topology topology and device device must match the local machine. The Level Zero must have been initialized with Sysman enabled (ZES_ENABLE_SYSMAN=1 in the environment). I/O devices detection and the Level Zero component are not needed in the topology.

    -

    The function only returns the locality of the device. If more information about the device is needed, OS objects should be used instead, see hwloc_levelzero_get_device_osdev().

    -

    This function is currently only implemented in a meaningful way for Linux; other systems will simply get a full cpuset.

    -
    Returns
    0 on success.
    -
    --1 on error, for instance if device information could not be found.
    - -
    -
    - -

    ◆ hwloc_levelzero_get_device_osdev()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_levelzero_get_device_osdev (hwloc_topology_t topology,
    ze_device_handle_t device 
    )
    -     		-inlinestatic
    -
    - -

    Get the hwloc OS device object corresponding to Level Zero device device.

    -
    Returns
    The hwloc OS device object that describes the given Level Zero device device.
    -
    -NULL if none could be found.
    -

    Topology topology and device dv_ind must match the local machine. I/O devices detection and the Level Zero component must be enabled in the topology. If not, the locality of the object may still be found using hwloc_levelzero_get_device_cpuset().

    -
    Note
    The corresponding hwloc PCI device may be found by looking at the result parent pointer (unless PCI devices are filtered out).
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    Interoperability with OpenGL displays
    -
    -
    - - - - - - - - -

    -Functions

    static hwloc_obj_t hwloc_gl_get_display_osdev_by_port_device (hwloc_topology_t topology, unsigned port, unsigned device)
     
    static hwloc_obj_t hwloc_gl_get_display_osdev_by_name (hwloc_topology_t topology, const char *name)
     
    static int hwloc_gl_get_display_by_osdev (hwloc_topology_t topology, hwloc_obj_t osdev, unsigned *port, unsigned *device)
     
    -

    Detailed Description

    -

    This interface offers ways to retrieve topology information about OpenGL displays.

    -

    Only the NVIDIA display locality information is currently available, using the NV-CONTROL X11 extension and the NVCtrl library.

    -

    Function Documentation

    - -

    ◆ hwloc_gl_get_display_by_osdev()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_gl_get_display_by_osdev (hwloc_topology_t topology,
    hwloc_obj_t osdev,
    unsigned * port,
    unsigned * device 
    )
    -     		-inlinestatic
    -
    - -

    Get the OpenGL display port and device corresponding to the given hwloc OS object.

    -

    Retrieves the OpenGL display port (server) in port and device (screen) in screen that correspond to the given hwloc OS device object.

    -
    Returns
    0 on success.
    -
    --1 if none could be found.
    -

    The topology topology does not necessarily have to match the current machine. For instance the topology may be an XML import of a remote host. I/O devices detection and the GL component must be enabled in the topology.

    - -
    -
    - -

    ◆ hwloc_gl_get_display_osdev_by_name()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_gl_get_display_osdev_by_name (hwloc_topology_t topology,
    const char * name 
    )
    -     		-inlinestatic
    -
    - -

    Get the hwloc OS device object corresponding to the OpenGL display given by name.

    -
    Returns
    The hwloc OS device object describing the OpenGL display whose name is name, built as ":port.device" such as ":0.0" .
    -
    -NULL if none could be found.
    -

    The topology topology does not necessarily have to match the current machine. For instance the topology may be an XML import of a remote host. I/O devices detection and the GL component must be enabled in the topology.

    -
    Note
    The corresponding PCI device object can be obtained by looking at the OS device parent object (unless PCI devices are filtered out).
    - -
    -
    - -

    ◆ hwloc_gl_get_display_osdev_by_port_device()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_gl_get_display_osdev_by_port_device (hwloc_topology_t topology,
    unsigned port,
    unsigned device 
    )
    -     		-inlinestatic
    -
    - -

    Get the hwloc OS device object corresponding to the OpenGL display given by port and device index.

    -
    Returns
    The hwloc OS device object describing the OpenGL display whose port (server) is port and device (screen) is device.
    -
    -NULL if none could be found.
    -

    The topology topology does not necessarily have to match the current machine. For instance the topology may be an XML import of a remote host. I/O devices detection and the GL component must be enabled in the topology.

    -
    Note
    The corresponding PCI device object can be obtained by looking at the OS device parent object (unless PCI devices are filtered out).
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    Interoperability with OpenFabrics
    -
    -
    - - - - - - - - -

    -Functions

    static int hwloc_ibv_get_device_cpuset (hwloc_topology_t topology, struct ibv_device *ibdev, hwloc_cpuset_t set)
     
    static hwloc_obj_t hwloc_ibv_get_device_osdev_by_name (hwloc_topology_t topology, const char *ibname)
     
    static hwloc_obj_t hwloc_ibv_get_device_osdev (hwloc_topology_t topology, struct ibv_device *ibdev)
     
    -

    Detailed Description

    -

    This interface offers ways to retrieve topology information about OpenFabrics devices (InfiniBand, Omni-Path, usNIC, etc).

    -

    Function Documentation

    - -

    ◆ hwloc_ibv_get_device_cpuset()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    static int hwloc_ibv_get_device_cpuset (hwloc_topology_t topology,
    struct ibv_device * ibdev,
    hwloc_cpuset_t set 
    )
    -     		-inlinestatic
    -
    - -

    Get the CPU set of processors that are physically close to device ibdev.

    -

    Store in set the CPU-set describing the locality of the OpenFabrics device ibdev (InfiniBand, etc).

    -

    Topology topology and device ibdev must match the local machine. I/O devices detection is not needed in the topology.

    -

    The function only returns the locality of the device. If more information about the device is needed, OS objects should be used instead, see hwloc_ibv_get_device_osdev() and hwloc_ibv_get_device_osdev_by_name().

    -

    This function is currently only implemented in a meaningful way for Linux; other systems will simply get a full cpuset.

    -
    Returns
    0 on success.
    -
    --1 on error, for instance if device information could not be found.
    - -
    -
    - -

    ◆ hwloc_ibv_get_device_osdev()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_ibv_get_device_osdev (hwloc_topology_t topology,
    struct ibv_device * ibdev 
    )
    -     		-inlinestatic
    -
    - -

    Get the hwloc OS device object corresponding to the OpenFabrics device ibdev.

    -
    Returns
    The hwloc OS device object describing the OpenFabrics device ibdev (InfiniBand, etc).
    -
    -NULL if none could be found.
    -

    Topology topology and device ibdev must match the local machine. I/O devices detection must be enabled in the topology. If not, the locality of the object may still be found using hwloc_ibv_get_device_cpuset().

    -
    Note
    The corresponding PCI device object can be obtained by looking at the OS device parent object.
    - -
    -
    - -

    ◆ hwloc_ibv_get_device_osdev_by_name()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static hwloc_obj_t hwloc_ibv_get_device_osdev_by_name (hwloc_topology_t topology,
    const char * ibname 
    )
    -     		-inlinestatic
    -
    - -

    Get the hwloc OS device object corresponding to the OpenFabrics device named ibname.

    -
    Returns
    The hwloc OS device object describing the OpenFabrics device (InfiniBand, Omni-Path, usNIC, etc) whose name is ibname (mlx5_0, hfi1_0, usnic_0, qib0, etc).
    -
    -NULL if none could be found.
    -

    The name ibname is usually obtained from ibv_get_device_name().

    -

    The topology topology does not necessarily have to match the current machine. For instance the topology may be an XML import of a remote host. I/O devices detection must be enabled in the topology.

    -
    Note
    The corresponding PCI device object can be obtained by looking at the OS device parent object.
    - -
    -
    -
    - - - - - - - -
    -
    -Data Structures | -Typedefs | -Enumerations | -Functions
    -
    Topology differences
    -
    -
    - - - - - - -

    -Data Structures

    union  hwloc_topology_diff_obj_attr_u
     
    union  hwloc_topology_diff_u
     
    - - - - - - - -

    -Typedefs

    typedef enum hwloc_topology_diff_obj_attr_type_e hwloc_topology_diff_obj_attr_type_t
     
    typedef enum hwloc_topology_diff_type_e hwloc_topology_diff_type_t
     
    typedef union hwloc_topology_diff_u * hwloc_topology_diff_t
     
    - - - - - - - -

    -Enumerations

    enum  hwloc_topology_diff_obj_attr_type_e { HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_SIZE -, HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_NAME -, HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_INFO - }
     
    enum  hwloc_topology_diff_type_e { HWLOC_TOPOLOGY_DIFF_OBJ_ATTR -, HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX - }
     
    enum  hwloc_topology_diff_apply_flags_e { HWLOC_TOPOLOGY_DIFF_APPLY_REVERSE - }
     
    - - - - - - - - - - - - - - - -

    -Functions

    int hwloc_topology_diff_build (hwloc_topology_t topology, hwloc_topology_t newtopology, unsigned long flags, hwloc_topology_diff_t *diff)
     
    int hwloc_topology_diff_apply (hwloc_topology_t topology, hwloc_topology_diff_t diff, unsigned long flags)
     
    int hwloc_topology_diff_destroy (hwloc_topology_diff_t diff)
     
    int hwloc_topology_diff_load_xml (const char *xmlpath, hwloc_topology_diff_t *diff, char **refname)
     
    int hwloc_topology_diff_export_xml (hwloc_topology_diff_t diff, const char *refname, const char *xmlpath)
     
    int hwloc_topology_diff_load_xmlbuffer (const char *xmlbuffer, int buflen, hwloc_topology_diff_t *diff, char **refname)
     
    int hwloc_topology_diff_export_xmlbuffer (hwloc_topology_diff_t diff, const char *refname, char **xmlbuffer, int *buflen)
     
    -

    Detailed Description

    -

    Applications that manipulate many similar topologies, for instance one for each node of a homogeneous cluster, may want to compress topologies to reduce the memory footprint.

    -

    This file offers a way to manipulate the difference between topologies and export/import it to/from XML. Compression may therefore be achieved by storing one topology entirely while the others are only described by their differences with the former. The actual topology can be reconstructed when actually needed by applying the precomputed difference to the reference topology.

    -

    This interface targets very similar nodes. Only very simple differences between topologies are actually supported, for instance a change in the memory size, the name of the object, or some info attribute. More complex differences such as adding or removing objects cannot be represented in the difference structures and therefore return errors. Differences between object sets or topology-wide allowed sets, cannot be represented either.

    -

    It means that there is no need to apply the difference when looking at the tree organization (how many levels, how many objects per level, what kind of objects, CPU and node sets, etc) and when binding to objects. However the difference must be applied when looking at object attributes such as the name, the memory size or info attributes.

    -

    Typedef Documentation

    - -

    ◆ hwloc_topology_diff_obj_attr_type_t

    - -
    -
    - - - - -
    typedef enum hwloc_topology_diff_obj_attr_type_e hwloc_topology_diff_obj_attr_type_t
    -
    - -

    Type of one object attribute difference.

    - -
    -
    - -

    ◆ hwloc_topology_diff_t

    - -
    -
    - - - - -
    typedef union hwloc_topology_diff_u * hwloc_topology_diff_t
    -
    - -

    One element of a difference list between two topologies.

    - -
    -
    - -

    ◆ hwloc_topology_diff_type_t

    - -
    -
    - - - - -
    typedef enum hwloc_topology_diff_type_e hwloc_topology_diff_type_t
    -
    - -

    Type of one element of a difference list.

    - -
    -
    -

    Enumeration Type Documentation

    - -

    ◆ hwloc_topology_diff_apply_flags_e

    - -
    -
    - - - - -
    enum hwloc_topology_diff_apply_flags_e
    -
    - -

    Flags to be given to hwloc_topology_diff_apply().

    - - -
    Enumerator
    HWLOC_TOPOLOGY_DIFF_APPLY_REVERSE 

    Apply topology diff in reverse direction.

    -
    - -
    -
    - -

    ◆ hwloc_topology_diff_obj_attr_type_e

    - -
    -
    - - - - -
    enum hwloc_topology_diff_obj_attr_type_e
    -
    - -

    Type of one object attribute difference.

    - - - - -
    Enumerator
    HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_SIZE 

    The object local memory is modified. The union is a hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s (and the index field is ignored).

    -
    HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_NAME 

    The object name is modified. The union is a hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s (and the name field is ignored).

    -
    HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_INFO 

    the value of an info attribute is modified. The union is a hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s.

    -
    - -
    -
    - -

    ◆ hwloc_topology_diff_type_e

    - -
    -
    - - - - -
    enum hwloc_topology_diff_type_e
    -
    - -

    Type of one element of a difference list.

    - - - -
    Enumerator
    HWLOC_TOPOLOGY_DIFF_OBJ_ATTR 

    An object attribute was changed. The union is a hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s.

    -
    HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX 

    The difference is too complex, it cannot be represented. The difference below this object has not been checked. hwloc_topology_diff_build() will return 1.

    -

    The union is a hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s.

    -
    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_topology_diff_apply()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_diff_apply (hwloc_topology_t topology,
    hwloc_topology_diff_t diff,
    unsigned long flags 
    )
    -
    - -

    Apply a topology diff to an existing topology.

    -

    flags is an OR'ed set of hwloc_topology_diff_apply_flags_e.

    -

    The new topology is modified in place. hwloc_topology_dup() may be used to duplicate it before patching.

    -

    If the difference cannot be applied entirely, all previous applied elements are unapplied before returning.

    -
    Returns
    0 on success.
    -
    --N if applying the difference failed while trying to apply the N-th part of the difference. For instance -1 is returned if the very first difference element could not be applied.
    - -
    -
    - -

    ◆ hwloc_topology_diff_build()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_diff_build (hwloc_topology_t topology,
    hwloc_topology_t newtopology,
    unsigned long flags,
    hwloc_topology_diff_t * diff 
    )
    -
    - -

    Compute the difference between 2 topologies.

    -

    The difference is stored as a list of hwloc_topology_diff_t entries starting at diff. It is computed by doing a depth-first traversal of both topology trees simultaneously.

    -

    If the difference between 2 objects is too complex to be represented (for instance if some objects have different types, or different numbers of children), a special diff entry of type HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX is queued. The computation of the diff does not continue below these objects. So each such diff entry means that the difference between two subtrees could not be computed.

    -
    Returns
    0 if the difference can be represented properly.
    -
    -0 with diff pointing to NULL if there is no difference between the topologies.
    -
    -1 if the difference is too complex (see above). Some entries in the list will be of type HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX.
    -
    --1 on any other error.
    -
    Note
    flags is currently not used. It should be 0.
    -
    -The output diff has to be freed with hwloc_topology_diff_destroy().
    -
    -The output diff can only be exported to XML or passed to hwloc_topology_diff_apply() if 0 was returned, i.e. if no entry of type HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX is listed.
    -
    -The output diff may be modified by removing some entries from the list. The removed entries should be freed by passing them to to hwloc_topology_diff_destroy() (possible as another list).
    - -
    -
    - -

    ◆ hwloc_topology_diff_destroy()

    - -
    -
    - - - - - - - - -
    int hwloc_topology_diff_destroy (hwloc_topology_diff_t diff)
    -
    - -

    Destroy a list of topology differences.

    -
    Returns
    0.
    - -
    -
    - -

    ◆ hwloc_topology_diff_export_xml()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_diff_export_xml (hwloc_topology_diff_t diff,
    const char * refname,
    const char * xmlpath 
    )
    -
    - -

    Export a list of topology differences to a XML file.

    -

    If not NULL, refname defines an identifier string for the reference topology which was used as a base when computing this difference. This identifier is usually the name of the other XML file that contains the reference topology. This attribute is given back when reading the diff from XML.

    -
    Returns
    0 on success, -1 on error.
    - -
    -
    - -

    ◆ hwloc_topology_diff_export_xmlbuffer()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_diff_export_xmlbuffer (hwloc_topology_diff_t diff,
    const char * refname,
    char ** xmlbuffer,
    int * buflen 
    )
    -
    - -

    Export a list of topology differences to a XML buffer.

    -

    If not NULL, refname defines an identifier string for the reference topology which was used as a base when computing this difference. This identifier is usually the name of the other XML file that contains the reference topology. This attribute is given back when reading the diff from XML.

    -

    The returned buffer ends with a \0 that is included in the returned length.

    -
    Returns
    0 on success, -1 on error.
    -
    Note
    The XML buffer should later be freed with hwloc_free_xmlbuffer().
    - -
    -
    - -

    ◆ hwloc_topology_diff_load_xml()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_diff_load_xml (const char * xmlpath,
    hwloc_topology_diff_t * diff,
    char ** refname 
    )
    -
    - -

    Load a list of topology differences from a XML file.

    -

    If not NULL, refname will be filled with the identifier string of the reference topology for the difference file, if any was specified in the XML file. This identifier is usually the name of the other XML file that contains the reference topology.

    -
    Returns
    0 on success, -1 on error.
    -
    Note
    the pointer returned in refname should later be freed by the caller.
    - -
    -
    - -

    ◆ hwloc_topology_diff_load_xmlbuffer()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_diff_load_xmlbuffer (const char * xmlbuffer,
    int buflen,
    hwloc_topology_diff_t * diff,
    char ** refname 
    )
    -
    - -

    Load a list of topology differences from a XML buffer.

    -

    If not NULL, refname will be filled with the identifier string of the reference topology for the difference file, if any was specified in the XML file. This identifier is usually the name of the other XML file that contains the reference topology.

    -
    Returns
    0 on success, -1 on error.
    -
    Note
    the pointer returned in refname should later be freed by the caller.
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    Sharing topologies between processes
    -
    -
    - - - - - - - - -

    -Functions

    int hwloc_shmem_topology_get_length (hwloc_topology_t topology, size_t *lengthp, unsigned long flags)
     
    int hwloc_shmem_topology_write (hwloc_topology_t topology, int fd, hwloc_uint64_t fileoffset, void *mmap_address, size_t length, unsigned long flags)
     
    int hwloc_shmem_topology_adopt (hwloc_topology_t *topologyp, int fd, hwloc_uint64_t fileoffset, void *mmap_address, size_t length, unsigned long flags)
     
    -

    Detailed Description

    -

    These functions are used to share a topology between processes by duplicating it into a file-backed shared-memory buffer.

    -

    The master process must first get the required shared-memory size for storing this topology with hwloc_shmem_topology_get_length().

    -

    Then it must find a virtual memory area of that size that is available in all processes (identical virtual addresses in all processes). On Linux, this can be done by comparing holes found in /proc/<pid>/maps for each process.

    -

    Once found, it must open a destination file for storing the buffer, and pass it to hwloc_shmem_topology_write() together with virtual memory address and length obtained above.

    -

    Other processes may then adopt this shared topology by opening the same file and passing it to hwloc_shmem_topology_adopt() with the exact same virtual memory address and length.

    -

    Function Documentation

    - -

    ◆ hwloc_shmem_topology_adopt()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_shmem_topology_adopt (hwloc_topology_t * topologyp,
    int fd,
    hwloc_uint64_t fileoffset,
    void * mmap_address,
    size_t length,
    unsigned long flags 
    )
    -
    - -

    Adopt a shared memory topology stored in a file.

    -

    Map a file in virtual memory and adopt the topology that was previously stored there with hwloc_shmem_topology_write().

    -

    The returned adopted topology in topologyp can be used just like any topology. And it must be destroyed with hwloc_topology_destroy() as usual.

    -

    However the topology is read-only. For instance, it cannot be modified with hwloc_topology_restrict() and object userdata pointers cannot be changed.

    -

    The segment of the file pointed by descriptor fd, starting at offset fileoffset, and of length length (in bytes), will be mapped at virtual address mmap_address.

    -

    The file pointed by descriptor fd, the offset fileoffset, the requested mapping virtual address mmap_address and the length length must be identical to what was given to hwloc_shmem_topology_write() earlier.

    -
    Note
    Flags flags are currently unused, must be 0.
    -
    -The object userdata pointer should not be used unless the process that created the shared topology also placed userdata-pointed buffers in shared memory.
    -
    -This function takes care of calling hwloc_topology_abi_check().
    -
    Returns
    0 on success.
    -
    --1 with errno set to EBUSY if the virtual memory mapping defined by mmap_address and length isn't available in the process.
    -
    --1 with errno set to EINVAL if fileoffset, mmap_address or length aren't page-aligned, or do not match what was given to hwloc_shmem_topology_write() earlier.
    -
    --1 with errno set to EINVAL if the layout of the topology structure is different between the writer process and the adopter process.
    - -
    -
    - -

    ◆ hwloc_shmem_topology_get_length()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_shmem_topology_get_length (hwloc_topology_t topology,
    size_t * lengthp,
    unsigned long flags 
    )
    -
    - -

    Get the required shared memory length for storing a topology.

    -

    This length (in bytes) must be used in hwloc_shmem_topology_write() and hwloc_shmem_topology_adopt() later.

    -
    Returns
    the length, or -1 on error, for instance if flags are invalid.
    -
    Note
    Flags flags are currently unused, must be 0.
    - -
    -
    - -

    ◆ hwloc_shmem_topology_write()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_shmem_topology_write (hwloc_topology_t topology,
    int fd,
    hwloc_uint64_t fileoffset,
    void * mmap_address,
    size_t length,
    unsigned long flags 
    )
    -
    - -

    Duplicate a topology to a shared memory file.

    -

    Temporarily map a file in virtual memory and duplicate the topology topology by allocating duplicates in there.

    -

    The segment of the file pointed by descriptor fd, starting at offset fileoffset, and of length length (in bytes), will be temporarily mapped at virtual address mmap_address during the duplication.

    -

    The mapping length length must have been previously obtained with hwloc_shmem_topology_get_length() and the topology must not have been modified in the meantime.

    -
    Note
    Flags flags are currently unused, must be 0.
    -
    -The object userdata pointer is duplicated but the pointed buffer is not. However the caller may also allocate it manually in shared memory to share it as well.
    -
    Returns
    0 on success.
    -
    --1 with errno set to EBUSY if the virtual memory mapping defined by mmap_address and length isn't available in the process.
    -
    --1 with errno set to EINVAL if fileoffset, mmap_address or length aren't page-aligned.
    - -
    -
    -
    - - - - - - - -
    -
    -Data Structures
    -
    Components and Plugins: Discovery components
    -
    -
    - - - - -

    -Data Structures

    struct  hwloc_disc_component
     
    -

    Detailed Description

    -
    Note
    These structures and functions may change when HWLOC_COMPONENT_ABI is modified.
    -
    - - - - - - - -
    -
    -Data Structures | -Typedefs | -Enumerations | -Functions
    -
    Components and Plugins: Discovery backends
    -
    -
    - - - - - - -

    -Data Structures

    struct  hwloc_disc_status
     
    struct  hwloc_backend
     
    - - - -

    -Typedefs

    typedef enum hwloc_disc_phase_e hwloc_disc_phase_t
     
    - - - - - -

    -Enumerations

    enum  hwloc_disc_phase_e {
    -  HWLOC_DISC_PHASE_GLOBAL -, HWLOC_DISC_PHASE_CPU -, HWLOC_DISC_PHASE_MEMORY -, HWLOC_DISC_PHASE_PCI -,
    -  HWLOC_DISC_PHASE_IO -, HWLOC_DISC_PHASE_MISC -, HWLOC_DISC_PHASE_ANNOTATE -, HWLOC_DISC_PHASE_TWEAK -
    - }
     
    enum  hwloc_disc_status_flag_e { HWLOC_DISC_STATUS_FLAG_GOT_ALLOWED_RESOURCES - }
     
    - - - - - -

    -Functions

    struct hwloc_backend * hwloc_backend_alloc (struct hwloc_topology *topology, struct hwloc_disc_component *component)
     
    int hwloc_backend_enable (struct hwloc_backend *backend)
     
    -

    Detailed Description

    -
    Note
    These structures and functions may change when HWLOC_COMPONENT_ABI is modified.
    -

    Typedef Documentation

    - -

    ◆ hwloc_disc_phase_t

    - -
    -
    - - - - -
    typedef enum hwloc_disc_phase_e hwloc_disc_phase_t
    -
    - -

    Discovery phase.

    - -
    -
    -

    Enumeration Type Documentation

    - -

    ◆ hwloc_disc_phase_e

    - -
    -
    - - - - -
    enum hwloc_disc_phase_e
    -
    - -

    Discovery phase.

    - - - - - - - - - -
    Enumerator
    HWLOC_DISC_PHASE_GLOBAL 

    xml or synthetic, platform-specific components such as bgq. Discovers everything including CPU, memory, I/O and everything else. A component with a Global phase usually excludes all other phases.

    -
    HWLOC_DISC_PHASE_CPU 

    CPU discovery.

    -
    HWLOC_DISC_PHASE_MEMORY 

    Attach memory to existing CPU objects.

    -
    HWLOC_DISC_PHASE_PCI 

    Attach PCI devices and bridges to existing CPU objects.

    -
    HWLOC_DISC_PHASE_IO 

    I/O discovery that requires PCI devices (OS devices such as OpenCL, CUDA, etc.).

    -
    HWLOC_DISC_PHASE_MISC 

    Misc objects that gets added below anything else.

    -
    HWLOC_DISC_PHASE_ANNOTATE 

    Annotating existing objects, adding distances, etc.

    -
    HWLOC_DISC_PHASE_TWEAK 

    Final tweaks to a ready-to-use topology. This phase runs once the topology is loaded, before it is returned to the topology. Hence it may only use the main hwloc API for modifying the topology, for instance by restricting it, adding info attributes, etc.

    -
    - -
    -
    - -

    ◆ hwloc_disc_status_flag_e

    - -
    -
    - - - - -
    enum hwloc_disc_status_flag_e
    -
    - -

    Discovery status flags.

    - - -
    Enumerator
    HWLOC_DISC_STATUS_FLAG_GOT_ALLOWED_RESOURCES 

    The sets of allowed resources were already retrieved.

    -
    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_backend_alloc()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    struct hwloc_backend * hwloc_backend_alloc (struct hwloc_topology * topology,
    struct hwloc_disc_component * component 
    )
    -
    - -

    Allocate a backend structure, set good default values, initialize backend->component and topology, etc. The caller will then modify whatever needed, and call hwloc_backend_enable().

    - -
    -
    - -

    ◆ hwloc_backend_enable()

    - -
    -
    - - - - - - - - -
    int hwloc_backend_enable (struct hwloc_backend * backend)
    -
    - -

    Enable a previously allocated and setup backend.

    - -
    -
    -
    - - - - - - - -
    -
    -Data Structures | -Typedefs | -Enumerations
    -
    Components and Plugins: Generic components
    -
    -
    - - - - -

    -Data Structures

    struct  hwloc_component
     
    - - - -

    -Typedefs

    typedef enum hwloc_component_type_e hwloc_component_type_t
     
    - - - -

    -Enumerations

    enum  hwloc_component_type_e { HWLOC_COMPONENT_TYPE_DISC -, HWLOC_COMPONENT_TYPE_XML - }
     
    -

    Detailed Description

    -
    Note
    These structures and functions may change when HWLOC_COMPONENT_ABI is modified.
    -

    Typedef Documentation

    - -

    ◆ hwloc_component_type_t

    - -
    -
    - - - - -
    typedef enum hwloc_component_type_e hwloc_component_type_t
    -
    - -

    Generic component type.

    - -
    -
    -

    Enumeration Type Documentation

    - -

    ◆ hwloc_component_type_e

    - -
    -
    - - - - -
    enum hwloc_component_type_e
    -
    - -

    Generic component type.

    - - - -
    Enumerator
    HWLOC_COMPONENT_TYPE_DISC 

    The data field must point to a struct hwloc_disc_component.

    -
    HWLOC_COMPONENT_TYPE_XML 

    The data field must point to a struct hwloc_xml_component.

    -
    - -
    -
    -
    - - - - - - - -
    -
    -Macros | -Functions
    -
    Components and Plugins: Core functions to be used by components
    -
    -
    - - - - - - -

    -Macros

    #define HWLOC_SHOW_CRITICAL_ERRORS()   (hwloc_hide_errors() < 2)
     
    #define HWLOC_SHOW_ALL_ERRORS()   (hwloc_hide_errors() == 0)
     
    - - - - - - - - - - - - - - - -

    -Functions

    int hwloc_hide_errors (void)
     
    hwloc_obj_t hwloc__insert_object_by_cpuset (struct hwloc_topology *topology, hwloc_obj_t root, hwloc_obj_t obj, const char *reason)
     
    void hwloc_insert_object_by_parent (struct hwloc_topology *topology, hwloc_obj_t parent, hwloc_obj_t obj)
     
    hwloc_obj_t hwloc_alloc_setup_object (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned os_index)
     
    int hwloc_obj_add_children_sets (hwloc_obj_t obj)
     
    int hwloc_topology_reconnect (hwloc_topology_t topology, unsigned long flags)
     
    static int hwloc_plugin_check_namespace (const char *pluginname, const char *symbol)
     
    -

    Detailed Description

    -
    Note
    These structures and functions may change when HWLOC_COMPONENT_ABI is modified.
    -

    Macro Definition Documentation

    - -

    ◆ HWLOC_SHOW_ALL_ERRORS

    - -
    -
    - - - - - - - -
    #define HWLOC_SHOW_ALL_ERRORS()   (hwloc_hide_errors() == 0)
    -
    - -
    -
    - -

    ◆ HWLOC_SHOW_CRITICAL_ERRORS

    - -
    -
    - - - - - - - -
    #define HWLOC_SHOW_CRITICAL_ERRORS()   (hwloc_hide_errors() < 2)
    -
    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc__insert_object_by_cpuset()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    hwloc_obj_t hwloc__insert_object_by_cpuset (struct hwloc_topology * topology,
    hwloc_obj_t root,
    hwloc_obj_t obj,
    const char * reason 
    )
    -
    - -

    Add an object to the topology.

    -

    Insert new object obj in the topology starting under existing object root (if NULL, the topology root object is used).

    -

    It is sorted along the tree of other objects according to the inclusion of cpusets, to eventually be added as a child of the smallest object including this object.

    -

    If the cpuset is empty, the type of the object (and maybe some attributes) must be enough to find where to insert the object. This is especially true for NUMA nodes with memory and no CPUs.

    -

    The given object should not have children.

    -

    This shall only be called before levels are built.

    -

    The caller should check whether the object type is filtered-out before calling this function.

    -

    The topology cpuset/nodesets will be enlarged to include the object sets.

    -

    reason is a unique string identifying where and why this insertion call was performed (it will be displayed in case of internal insertion error).

    -

    Returns the object on success. Returns NULL and frees obj on error. Returns another object and frees obj if it was merged with an identical pre-existing object.

    - -
    -
    - -

    ◆ hwloc_alloc_setup_object()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    hwloc_obj_t hwloc_alloc_setup_object (hwloc_topology_t topology,
    hwloc_obj_type_t type,
    unsigned os_index 
    )
    -
    - -

    Allocate and initialize an object of the given type and physical index.

    -

    If os_index is unknown or irrelevant, use HWLOC_UNKNOWN_INDEX.

    - -
    -
    - -

    ◆ hwloc_hide_errors()

    - -
    -
    - - - - - - - - -
    int hwloc_hide_errors (void )
    -
    - -

    Check whether error messages are hidden.

    -

    Callers should print critical error messages (e.g. invalid hw topo info, invalid config) only if this function returns strictly less than 2.

    -

    Callers should print non-critical error messages (e.g. failure to initialize CUDA) if this function returns 0.

    -

    This function return 1 by default (show critical only), 0 in lstopo (show all), or anything set in HWLOC_HIDE_ERRORS in the environment.

    -

    Use macros HWLOC_SHOW_CRITICAL_ERRORS() and HWLOC_SHOW_ALL_ERRORS() for clarity.

    - -
    -
    - -

    ◆ hwloc_insert_object_by_parent()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    void hwloc_insert_object_by_parent (struct hwloc_topology * topology,
    hwloc_obj_t parent,
    hwloc_obj_t obj 
    )
    -
    - -

    Insert an object somewhere in the topology.

    -

    It is added as the last child of the given parent. The cpuset is completely ignored, so strange objects such as I/O devices should preferably be inserted with this.

    -

    When used for "normal" children with cpusets (when importing from XML when duplicating a topology), the caller should make sure that:

      -
    • children are inserted in order,
      • -
    • children cpusets do not intersect.
      • -
    -

    The given object may have normal, I/O or Misc children, as long as they are in order as well. These children must have valid parent and next_sibling pointers.

    -

    The caller should check whether the object type is filtered-out before calling this function.

    - -
    -
    - -

    ◆ hwloc_obj_add_children_sets()

    - -
    -
    - - - - - - - - -
    int hwloc_obj_add_children_sets (hwloc_obj_t obj)
    -
    - -

    Setup object cpusets/nodesets by OR'ing its children.

    -

    Used when adding an object late in the topology. Will update the new object by OR'ing all its new children sets.

    -

    Used when PCI backend adds a hostbridge parent, when distances add a new Group, etc.

    - -
    -
    - -

    ◆ hwloc_plugin_check_namespace()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static int hwloc_plugin_check_namespace (const char * pluginname,
    const char * symbol 
    )
    -     		-inlinestatic
    -
    - -

    Make sure that plugins can lookup core symbols.

    -

    This is a sanity check to avoid lazy-lookup failures when libhwloc is loaded within a plugin, and later tries to load its own plugins. This may fail (and abort the program) if libhwloc symbols are in a private namespace.

    -
    Returns
    0 on success.
    -
    --1 if the plugin cannot be successfully loaded. The caller plugin init() callback should return a negative error code as well.
    -

    Plugins should call this function in their init() callback to avoid later crashes if lazy symbol resolution is used by the upper layer that loaded hwloc (e.g. OpenCL implementations using dlopen with RTLD_LAZY).

    -
    Note
    The build system must define HWLOC_INSIDE_PLUGIN if and only if building the caller as a plugin.
    -
    -This function should remain inline so plugins can call it even when they cannot find libhwloc symbols.
    - -
    -
    - -

    ◆ hwloc_topology_reconnect()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_topology_reconnect (hwloc_topology_t topology,
    unsigned long flags 
    )
    -
    - -

    Request a reconnection of children and levels in the topology.

    -

    May be used by backends during discovery if they need arrays or lists of object within levels or children to be fully connected.

    -

    flags is currently unused, must 0.

    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    Components and Plugins: Filtering objects
    -
    -
    - - - - - - - - - - -

    -Functions

    static int hwloc_filter_check_pcidev_subtype_important (unsigned classid)
     
    static int hwloc_filter_check_osdev_subtype_important (hwloc_obj_osdev_type_t subtype)
     
    static int hwloc_filter_check_keep_object_type (hwloc_topology_t topology, hwloc_obj_type_t type)
     
    static int hwloc_filter_check_keep_object (hwloc_topology_t topology, hwloc_obj_t obj)
     
    -

    Detailed Description

    -
    Note
    These structures and functions may change when HWLOC_COMPONENT_ABI is modified.
    -

    Function Documentation

    - -

    ◆ hwloc_filter_check_keep_object()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static int hwloc_filter_check_keep_object (hwloc_topology_t topology,
    hwloc_obj_t obj 
    )
    -     		-inlinestatic
    -
    - -

    Check whether the given object should be filtered-out.

    -
    Returns
    1 if the object type should be kept, 0 otherwise.
    - -
    -
    - -

    ◆ hwloc_filter_check_keep_object_type()

    - -
    -
    - - - - - -
    - - - - - - - - - - - - - - - - - - -
    static int hwloc_filter_check_keep_object_type (hwloc_topology_t topology,
    hwloc_obj_type_t type 
    )
    -     		-inlinestatic
    -
    - -

    Check whether a non-I/O object type should be filtered-out.

    -

    Cannot be used for I/O objects.

    -
    Returns
    1 if the object type should be kept, 0 otherwise.
    - -
    -
    - -

    ◆ hwloc_filter_check_osdev_subtype_important()

    - -
    -
    - - - - - -
    - - - - - - - - -
    static int hwloc_filter_check_osdev_subtype_important (hwloc_obj_osdev_type_t subtype)
    -     		-inlinestatic
    -
    - -

    Check whether the given OS device subtype is important.

    -
    Returns
    1 if important, 0 otherwise.
    - -
    -
    - -

    ◆ hwloc_filter_check_pcidev_subtype_important()

    - -
    -
    - - - - - -
    - - - - - - - - -
    static int hwloc_filter_check_pcidev_subtype_important (unsigned classid)
    -     		-inlinestatic
    -
    - -

    Check whether the given PCI device classid is important.

    -
    Returns
    1 if important, 0 otherwise.
    - -
    -
    -
    - - - - - - - -
    -
    -Functions
    -
    Components and Plugins: helpers for PCI discovery
    -
    -
    - - - - - - - - - - - - - - -

    -Functions

    unsigned hwloc_pcidisc_find_cap (const unsigned char *config, unsigned cap)
     
    int hwloc_pcidisc_find_linkspeed (const unsigned char *config, unsigned offset, float *linkspeed)
     
    hwloc_obj_type_t hwloc_pcidisc_check_bridge_type (unsigned device_class, const unsigned char *config)
     
    int hwloc_pcidisc_find_bridge_buses (unsigned domain, unsigned bus, unsigned dev, unsigned func, unsigned *secondary_busp, unsigned *subordinate_busp, const unsigned char *config)
     
    void hwloc_pcidisc_tree_insert_by_busid (struct hwloc_obj **treep, struct hwloc_obj *obj)
     
    int hwloc_pcidisc_tree_attach (struct hwloc_topology *topology, struct hwloc_obj *tree)
     
    -

    Detailed Description

    -
    Note
    These structures and functions may change when HWLOC_COMPONENT_ABI is modified.
    -

    Function Documentation

    - -

    ◆ hwloc_pcidisc_check_bridge_type()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    hwloc_obj_type_t hwloc_pcidisc_check_bridge_type (unsigned device_class,
    const unsigned char * config 
    )
    -
    - -

    Return the hwloc object type (PCI device or Bridge) for the given class and configuration space.

    -

    This function requires 16 bytes of common configuration header at the beginning of config.

    - -
    -
    - -

    ◆ hwloc_pcidisc_find_bridge_buses()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_pcidisc_find_bridge_buses (unsigned domain,
    unsigned bus,
    unsigned dev,
    unsigned func,
    unsigned * secondary_busp,
    unsigned * subordinate_busp,
    const unsigned char * config 
    )
    -
    - -

    Fills the attributes of the given PCI bridge using the given PCI config space.

    -

    This function requires 32 bytes of common configuration header at the beginning of config.

    -

    Returns -1 and destroys /p obj if bridge fields are invalid.

    - -
    -
    - -

    ◆ hwloc_pcidisc_find_cap()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    unsigned hwloc_pcidisc_find_cap (const unsigned char * config,
    unsigned cap 
    )
    -
    - -

    Return the offset of the given capability in the PCI config space buffer.

    -

    This function requires a 256-bytes config space. Unknown/unavailable bytes should be set to 0xff.

    - -
    -
    - -

    ◆ hwloc_pcidisc_find_linkspeed()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_pcidisc_find_linkspeed (const unsigned char * config,
    unsigned offset,
    float * linkspeed 
    )
    -
    - -

    Fill linkspeed by reading the PCI config space where PCI_CAP_ID_EXP is at position offset.

    -

    Needs 20 bytes of EXP capability block starting at offset in the config space for registers up to link status.

    - -
    -
    - -

    ◆ hwloc_pcidisc_tree_attach()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    int hwloc_pcidisc_tree_attach (struct hwloc_topology * topology,
    struct hwloc_obj * tree 
    )
    -
    - -

    Add some hostbridges on top of the given tree of PCI objects and attach them to the topology.

    -

    Other backends may lookup PCI objects or localities (for instance to attach OS devices) by using hwloc_pcidisc_find_by_busid() or hwloc_pcidisc_find_busid_parent().

    - -
    -
    - -

    ◆ hwloc_pcidisc_tree_insert_by_busid()

    - -
    -
    - - - - - - - - - - - - - - - - - - -
    void hwloc_pcidisc_tree_insert_by_busid (struct hwloc_obj ** treep,
    struct hwloc_obj * obj 
    )
    -
    - -

    Insert a PCI object in the given PCI tree by looking at PCI bus IDs.

    -

    If treep points to NULL, the new object is inserted there.

    - -
    -
    -
    - - - - - - - -
    -
    -Typedefs | -Functions
    -
    Components and Plugins: finding PCI objects during other discoveries
    -
    -
    - - - - -

    -Typedefs

    typedef void * hwloc_backend_distances_add_handle_t
     
    - - - - - - - - - - - -

    -Functions

    struct hwloc_obj * hwloc_pci_find_parent_by_busid (struct hwloc_topology *topology, unsigned domain, unsigned bus, unsigned dev, unsigned func)
     
    struct hwloc_obj * hwloc_pci_find_by_busid (struct hwloc_topology *topology, unsigned domain, unsigned bus, unsigned dev, unsigned func)
     
    hwloc_backend_distances_add_handle_t hwloc_backend_distances_add_create (hwloc_topology_t topology, const char *name, unsigned long kind, unsigned long flags)
     
    int hwloc_backend_distances_add_values (hwloc_topology_t topology, hwloc_backend_distances_add_handle_t handle, unsigned nbobjs, hwloc_obj_t *objs, hwloc_uint64_t *values, unsigned long flags)
     
    int hwloc_backend_distances_add_commit (hwloc_topology_t topology, hwloc_backend_distances_add_handle_t handle, unsigned long flags)
     
    -

    Detailed Description

    -
    Note
    These structures and functions may change when HWLOC_COMPONENT_ABI is modified.
    -

    Typedef Documentation

    - -

    ◆ hwloc_backend_distances_add_handle_t

    - -
    -
    - - - - -
    typedef void* hwloc_backend_distances_add_handle_t
    -
    - -

    Handle to a new distances structure during its addition to the topology.

    - -
    -
    -

    Function Documentation

    - -

    ◆ hwloc_backend_distances_add_commit()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_backend_distances_add_commit (hwloc_topology_t topology,
    hwloc_backend_distances_add_handle_t handle,
    unsigned long flags 
    )
    -
    - -

    Commit a new distances structure.

    -

    This is similar to hwloc_distances_add_commit() but this variant is designed for backend inserting distances during topology discovery.

    - -
    -
    - -

    ◆ hwloc_backend_distances_add_create()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    hwloc_backend_distances_add_handle_t hwloc_backend_distances_add_create (hwloc_topology_t topology,
    const char * name,
    unsigned long kind,
    unsigned long flags 
    )
    -
    - -

    Create a new empty distances structure.

    -

    This is identical to hwloc_distances_add_create() but this variant is designed for backend inserting distances during topology discovery.

    - -
    -
    - -

    ◆ hwloc_backend_distances_add_values()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    int hwloc_backend_distances_add_values (hwloc_topology_t topology,
    hwloc_backend_distances_add_handle_t handle,
    unsigned nbobjs,
    hwloc_obj_t * objs,
    hwloc_uint64_t * values,
    unsigned long flags 
    )
    -
    - -

    Specify the objects and values in a new empty distances structure.

    -

    This is similar to hwloc_distances_add_values() but this variant is designed for backend inserting distances during topology discovery.

    -

    The only semantical difference is that objs and values are not duplicated, but directly attached to the topology. On success, these arrays are given to the core and should not ever be freed by the caller anymore.

    - -
    -
    - -

    ◆ hwloc_pci_find_by_busid()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    struct hwloc_obj * hwloc_pci_find_by_busid (struct hwloc_topology * topology,
    unsigned domain,
    unsigned bus,
    unsigned dev,
    unsigned func 
    )
    -
    - -

    Find the PCI device or bridge matching a PCI bus ID exactly.

    -

    This is useful for adding specific information about some objects based on their PCI id. When it comes to attaching objects based on PCI locality, hwloc_pci_find_parent_by_busid() should be preferred.

    - -
    -
    - -

    ◆ hwloc_pci_find_parent_by_busid()

    - -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    struct hwloc_obj * hwloc_pci_find_parent_by_busid (struct hwloc_topology * topology,
    unsigned domain,
    unsigned bus,
    unsigned dev,
    unsigned func 
    )
    -
    - -

    Find the object or a parent of a PCI bus ID.

    -

    When attaching a new object (typically an OS device) whose locality is specified by PCI bus ID, this function returns the PCI object to use as a parent for attaching.

    -

    If the exact PCI device with this bus ID exists, it is returned. Otherwise (for instance if it was filtered out), the function returns another object with similar locality (for instance a parent bridge, or the local CPU Package).

    - -
    -
    -
    - - - - - - - -
    -
    -Enumerations
    -
    Netloc API
    -
    -
    - - - - -

    -Enumerations

    enum  {
    -  NETLOC_SUCCESS = 0 -, NETLOC_ERROR = -1 -, NETLOC_ERROR_NOTDIR = -2 -, NETLOC_ERROR_NOENT = -3 -,
    -  NETLOC_ERROR_EMPTY = -4 -, NETLOC_ERROR_MULTIPLE = -5 -, NETLOC_ERROR_NOT_IMPL = -6 -, NETLOC_ERROR_EXISTS = -7 -,
    -  NETLOC_ERROR_NOT_FOUND = -8 -, NETLOC_ERROR_MAX = -9 -
    - }
     
    -

    Detailed Description

    -

    Enumeration Type Documentation

    - -

    ◆ anonymous enum

    - -
    -
    - - - - -
    anonymous enum
    -
    -

    Return codes

    - - - - - - - - - - - -
    Enumerator
    NETLOC_SUCCESS 

    Success

    -
    NETLOC_ERROR 

    Error: General condition

    -
    NETLOC_ERROR_NOTDIR 

    Error: URI is not a directory

    -
    NETLOC_ERROR_NOENT 

    Error: URI is invalid, no such entry

    -
    NETLOC_ERROR_EMPTY 

    Error: No networks found

    -
    NETLOC_ERROR_MULTIPLE 

    Error: Multiple matching networks found

    -
    NETLOC_ERROR_NOT_IMPL 

    Error: Interface not implemented

    -
    NETLOC_ERROR_EXISTS 

    Error: If the entry already exists when trying to add to a lookup table

    -
    NETLOC_ERROR_NOT_FOUND 

    Error: No path found

    -
    NETLOC_ERROR_MAX 

    Error: Enum upper bound marker. No errors less than this number Will not be returned externally.

    -
    - -
    -
    -
    - - - - - - - -
    -
    -Data Fields
    -
    hwloc_obj Struct Reference
    Object Structure and Attributes
    -
    -
    - -

    #include <hwloc.h>

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

    -Data Fields

    hwloc_obj_type_t type
     
    char * subtype
     
    unsigned os_index
     
    char * name
     
    hwloc_uint64_t total_memory
     
    union hwloc_obj_attr_u * attr
     
    int depth
     
    unsigned logical_index
     
    struct hwloc_obj * next_cousin
     
    struct hwloc_obj * prev_cousin
     
    struct hwloc_obj * parent
     
    unsigned sibling_rank
     
    struct hwloc_obj * next_sibling
     
    struct hwloc_obj * prev_sibling
     
    int symmetric_subtree
     
    hwloc_cpuset_t cpuset
     
    hwloc_cpuset_t complete_cpuset
     
    hwloc_nodeset_t nodeset
     
    hwloc_nodeset_t complete_nodeset
     
    struct hwloc_info_s * infos
     
    unsigned infos_count
     
    void * userdata
     
    hwloc_uint64_t gp_index
     
    List and array of normal children below this object (except Memory, I/O and Misc children).
    unsigned arity
     
    struct hwloc_obj ** children
     
    struct hwloc_obj * first_child
     
    struct hwloc_obj * last_child
     
    List of Memory children below this object.
    unsigned memory_arity
     
    struct hwloc_obj * memory_first_child
     
    List of I/O children below this object.
    unsigned io_arity
     
    struct hwloc_obj * io_first_child
     
    List of Misc children below this object.
    unsigned misc_arity
     
    struct hwloc_obj * misc_first_child
     
    -

    Detailed Description

    -

    Structure of a topology object.

    -

    Applications must not modify any field except hwloc_obj.userdata.

    -

    Field Documentation

    - -

    ◆ arity

    - -
    -
    - - - - -
    unsigned hwloc_obj::arity
    -
    - -

    Number of normal children. Memory, Misc and I/O children are not listed here but rather in their dedicated children list.

    - -
    -
    - -

    ◆ attr

    - -
    -
    - - - - -
    union hwloc_obj_attr_u* hwloc_obj::attr
    -
    - -

    Object type-specific Attributes, may be NULL if no attribute value was found.

    - -
    -
    - -

    ◆ children

    - -
    -
    - - - - -
    struct hwloc_obj** hwloc_obj::children
    -
    - -

    Normal children, children[0 .. arity -1].

    - -
    -
    - -

    ◆ complete_cpuset

    - -
    -
    - - - - -
    hwloc_cpuset_t hwloc_obj::complete_cpuset
    -
    - -

    The complete CPU set of processors of this object,.

    -

    This may include not only the same as the cpuset field, but also some CPUs for which topology information is unknown or incomplete, some offlines CPUs, and the CPUs that are ignored when the HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED flag is not set. Thus no corresponding PU object may be found in the topology, because the precise position is undefined. It is however known that it would be somewhere under this object.

    -
    Note
    Its value must not be changed, hwloc_bitmap_dup() must be used instead.
    - -
    -
    - -

    ◆ complete_nodeset

    - -
    -
    - - - - -
    hwloc_nodeset_t hwloc_obj::complete_nodeset
    -
    - -

    The complete NUMA node set of this object,.

    -

    This may include not only the same as the nodeset field, but also some NUMA nodes for which topology information is unknown or incomplete, some offlines nodes, and the nodes that are ignored when the HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED flag is not set. Thus no corresponding NUMA node object may be found in the topology, because the precise position is undefined. It is however known that it would be somewhere under this object.

    -

    If there are no NUMA nodes in the machine, all the memory is close to this object, so only the first bit is set in complete_nodeset.

    -
    Note
    Its value must not be changed, hwloc_bitmap_dup() must be used instead.
    - -
    -
    - -

    ◆ cpuset

    - -
    -
    - - - - -
    hwloc_cpuset_t hwloc_obj::cpuset
    -
    - -

    CPUs covered by this object.

    -

    This is the set of CPUs for which there are PU objects in the topology under this object, i.e. which are known to be physically contained in this object and known how (the children path between this object and the PU objects).

    -

    If the HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED configuration flag is set, some of these CPUs may be online but not allowed for binding, see hwloc_topology_get_allowed_cpuset().

    -
    Note
    All objects have non-NULL CPU and node sets except Misc and I/O objects.
    -
    -Its value must not be changed, hwloc_bitmap_dup() must be used instead.
    - -
    -
    - -

    ◆ depth

    - -
    -
    - - - - -
    int hwloc_obj::depth
    -
    - -

    Vertical index in the hierarchy.

    -

    For normal objects, this is the depth of the horizontal level that contains this object and its cousins of the same type. If the topology is symmetric, this is equal to the parent depth plus one, and also equal to the number of parent/child links from the root object to here.

    -

    For special objects (NUMA nodes, I/O and Misc) that are not in the main tree, this is a special negative value that corresponds to their dedicated level, see hwloc_get_type_depth() and hwloc_get_type_depth_e. Those special values can be passed to hwloc functions such hwloc_get_nbobjs_by_depth() as usual.

    - -
    -
    - -

    ◆ first_child

    - -
    -
    - - - - -
    struct hwloc_obj* hwloc_obj::first_child
    -
    - -

    First normal child.

    - -
    -
    - -

    ◆ gp_index

    - -
    -
    - - - - -
    hwloc_uint64_t hwloc_obj::gp_index
    -
    - -

    Global persistent index. Generated by hwloc, unique across the topology (contrary to os_index) and persistent across topology changes (contrary to logical_index). Mostly used internally, but could also be used by application to identify objects.

    - -
    -
    - -

    ◆ infos

    - -
    -
    - - - - -
    struct hwloc_info_s* hwloc_obj::infos
    -
    - -

    Array of stringified info type=name.

    - -
    -
    - -

    ◆ infos_count

    - -
    -
    - - - - -
    unsigned hwloc_obj::infos_count
    -
    - -

    Size of infos array.

    - -
    -
    - -

    ◆ io_arity

    - -
    -
    - - - - -
    unsigned hwloc_obj::io_arity
    -
    - -

    Number of I/O children. These children are listed in io_first_child.

    - -
    -
    - -

    ◆ io_first_child

    - -
    -
    - - - - -
    struct hwloc_obj* hwloc_obj::io_first_child
    -
    - -

    First I/O child. Bridges, PCI and OS devices are listed here (io_arity and io_first_child) instead of in the normal children list. See also hwloc_obj_type_is_io().

    - -
    -
    - -

    ◆ last_child

    - -
    -
    - - - - -
    struct hwloc_obj* hwloc_obj::last_child
    -
    - -

    Last normal child.

    - -
    -
    - -

    ◆ logical_index

    - -
    -
    - - - - -
    unsigned hwloc_obj::logical_index
    -
    - -

    Horizontal index in the whole list of similar objects, hence guaranteed unique across the entire machine. Could be a "cousin_rank" since it's the rank within the "cousin" list below Note that this index may change when restricting the topology or when inserting a group.

    - -
    -
    - -

    ◆ memory_arity

    - -
    -
    - - - - -
    unsigned hwloc_obj::memory_arity
    -
    - -

    Number of Memory children. These children are listed in memory_first_child.

    - -
    -
    - -

    ◆ memory_first_child

    - -
    -
    - - - - -
    struct hwloc_obj* hwloc_obj::memory_first_child
    -
    - -

    First Memory child. NUMA nodes and Memory-side caches are listed here (memory_arity and memory_first_child) instead of in the normal children list. See also hwloc_obj_type_is_memory().

    -

    A memory hierarchy starts from a normal CPU-side object (e.g. Package) and ends with NUMA nodes as leaves. There might exist some memory-side caches between them in the middle of the memory subtree.

    - -
    -
    - -

    ◆ misc_arity

    - -
    -
    - - - - -
    unsigned hwloc_obj::misc_arity
    -
    - -

    Number of Misc children. These children are listed in misc_first_child.

    - -
    -
    - -

    ◆ misc_first_child

    - -
    -
    - - - - -
    struct hwloc_obj* hwloc_obj::misc_first_child
    -
    - -

    First Misc child. Misc objects are listed here (misc_arity and misc_first_child) instead of in the normal children list.

    - -
    -
    - -

    ◆ name

    - -
    -
    - - - - -
    char* hwloc_obj::name
    -
    - -

    Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name string is more useful than numerical indexes.

    - -
    -
    - -

    ◆ next_cousin

    - -
    -
    - - - - -
    struct hwloc_obj* hwloc_obj::next_cousin
    -
    - -

    Next object of same type and depth.

    - -
    -
    - -

    ◆ next_sibling

    - -
    -
    - - - - -
    struct hwloc_obj* hwloc_obj::next_sibling
    -
    - -

    Next object below the same parent (inside the same list of children).

    - -
    -
    - -

    ◆ nodeset

    - -
    -
    - - - - -
    hwloc_nodeset_t hwloc_obj::nodeset
    -
    - -

    NUMA nodes covered by this object or containing this object.

    -

    This is the set of NUMA nodes for which there are NUMA node objects in the topology under or above this object, i.e. which are known to be physically contained in this object or containing it and known how (the children path between this object and the NUMA node objects).

    -

    In the end, these nodes are those that are close to the current object. Function hwloc_get_local_numanode_objs() may be used to list those NUMA nodes more precisely.

    -

    If the HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED configuration flag is set, some of these nodes may be online but not allowed for allocation, see hwloc_topology_get_allowed_nodeset().

    -

    If there are no NUMA nodes in the machine, all the memory is close to this object, so only the first bit may be set in nodeset.

    -
    Note
    All objects have non-NULL CPU and node sets except Misc and I/O objects.
    -
    -Its value must not be changed, hwloc_bitmap_dup() must be used instead.
    - -
    -
    - -

    ◆ os_index

    - -
    -
    - - - - -
    unsigned hwloc_obj::os_index
    -
    - -

    OS-provided physical index number. It is not guaranteed unique across the entire machine, except for PUs and NUMA nodes. Set to HWLOC_UNKNOWN_INDEX if unknown or irrelevant for this object.

    - -
    -
    - -

    ◆ parent

    - -
    -
    - - - - -
    struct hwloc_obj* hwloc_obj::parent
    -
    - -

    Parent, NULL if root (Machine object)

    - -
    -
    - -

    ◆ prev_cousin

    - -
    -
    - - - - -
    struct hwloc_obj* hwloc_obj::prev_cousin
    -
    - -

    Previous object of same type and depth.

    - -
    -
    - -

    ◆ prev_sibling

    - -
    -
    - - - - -
    struct hwloc_obj* hwloc_obj::prev_sibling
    -
    - -

    Previous object below the same parent (inside the same list of children).

    - -
    -
    - -

    ◆ sibling_rank

    - -
    -
    - - - - -
    unsigned hwloc_obj::sibling_rank
    -
    - -

    Index in parent's children[] array. Or the index in parent's Memory, I/O or Misc children list.

    - -
    -
    - -

    ◆ subtype

    - -
    -
    - - - - -
    char* hwloc_obj::subtype
    -
    - -

    Subtype string to better describe the type field.

    - -
    -
    - -

    ◆ symmetric_subtree

    - -
    -
    - - - - -
    int hwloc_obj::symmetric_subtree
    -
    - -

    Set if the subtree of normal objects below this object is symmetric, which means all normal children and their children have identical subtrees.

    -

    Memory, I/O and Misc children are ignored.

    -

    If set in the topology root object, lstopo may export the topology as a synthetic string.

    - -
    -
    - -

    ◆ total_memory

    - -
    -
    - - - - -
    hwloc_uint64_t hwloc_obj::total_memory
    -
    - -

    Total memory (in bytes) in NUMA nodes below this object.

    - -
    -
    - -

    ◆ type

    - -
    -
    - - - - -
    hwloc_obj_type_t hwloc_obj::type
    -
    - -

    Type of object.

    - -
    -
    - -

    ◆ userdata

    - -
    -
    - - - - -
    void* hwloc_obj::userdata
    -
    - -

    Application-given private data pointer, initialized to NULL, use it as you wish. See hwloc_topology_set_userdata_export_callback() in hwloc/export.h if you wish to export this field to XML.

    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - -
    -
    -Data Structures | -Data Fields
    -
    hwloc_obj_attr_u Union Reference
    Object Structure and Attributes
    -
    -
    - -

    #include <hwloc.h>

    - - - - - - - - - - - - - - -

    -Data Structures

    struct  hwloc_bridge_attr_s
     
    struct  hwloc_cache_attr_s
     
    struct  hwloc_group_attr_s
     
    struct  hwloc_numanode_attr_s
     
    struct  hwloc_osdev_attr_s
     
    struct  hwloc_pcidev_attr_s
     
    - - - - - - - - - - - - - -

    -Data Fields

    struct hwloc_obj_attr_u::hwloc_numanode_attr_s numanode
     
    struct hwloc_obj_attr_u::hwloc_cache_attr_s cache
     
    struct hwloc_obj_attr_u::hwloc_group_attr_s group
     
    struct hwloc_obj_attr_u::hwloc_pcidev_attr_s pcidev
     
    struct hwloc_obj_attr_u::hwloc_bridge_attr_s bridge
     
    struct hwloc_obj_attr_u::hwloc_osdev_attr_s osdev
     
    -

    Detailed Description

    -

    Object type-specific Attributes.

    -

    Field Documentation

    - -

    ◆ bridge

    - -
    -
    - - - - -
    struct hwloc_obj_attr_u::hwloc_bridge_attr_s hwloc_obj_attr_u::bridge
    -
    - -
    -
    - -

    ◆ cache

    - -
    -
    - - - - -
    struct hwloc_obj_attr_u::hwloc_cache_attr_s hwloc_obj_attr_u::cache
    -
    - -
    -
    - -

    ◆ group

    - -
    -
    - - - - -
    struct hwloc_obj_attr_u::hwloc_group_attr_s hwloc_obj_attr_u::group
    -
    - -
    -
    - -

    ◆ numanode

    - -
    -
    - - - - -
    struct hwloc_obj_attr_u::hwloc_numanode_attr_s hwloc_obj_attr_u::numanode
    -
    - -
    -
    - -

    ◆ osdev

    - -
    -
    - - - - -
    struct hwloc_obj_attr_u::hwloc_osdev_attr_s hwloc_obj_attr_u::osdev
    -
    - -
    -
    - -

    ◆ pcidev

    - -
    -
    - - - - -
    struct hwloc_obj_attr_u::hwloc_pcidev_attr_s hwloc_obj_attr_u::pcidev
    -
    - -
    -
    -
    The documentation for this union was generated from the following file: -
    - - - - - - - - -
    -
    -Data Structures | -Data Fields
    -
    hwloc_obj_attr_u::hwloc_numanode_attr_s Struct Reference
    -
    -
    - -

    #include <hwloc.h>

    - - - - -

    -Data Structures

    struct  hwloc_memory_page_type_s
     
    - - - - - - - -

    -Data Fields

    hwloc_uint64_t local_memory
     
    unsigned page_types_len
     
    struct hwloc_obj_attr_u::hwloc_numanode_attr_s::hwloc_memory_page_type_s * page_types
     
    -

    Detailed Description

    -

    NUMA node-specific Object Attributes.

    -

    Field Documentation

    - -

    ◆ local_memory

    - -
    -
    - - - - -
    hwloc_uint64_t hwloc_obj_attr_u::hwloc_numanode_attr_s::local_memory
    -
    - -

    Local memory (in bytes)

    - -
    -
    - -

    ◆ page_types

    - -
    -
    - - - - -
    struct hwloc_obj_attr_u::hwloc_numanode_attr_s::hwloc_memory_page_type_s * hwloc_obj_attr_u::hwloc_numanode_attr_s::page_types
    -
    - -
    -
    - -

    ◆ page_types_len

    - -
    -
    - - - - -
    unsigned hwloc_obj_attr_u::hwloc_numanode_attr_s::page_types_len
    -
    - -

    Size of array page_types.

    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - - -
    -
    -Data Fields
    -
    hwloc_obj_attr_u::hwloc_numanode_attr_s::hwloc_memory_page_type_s Struct Reference
    -
    -
    - -

    #include <hwloc.h>

    - - - - - - -

    -Data Fields

    hwloc_uint64_t size
     
    hwloc_uint64_t count
     
    -

    Detailed Description

    -

    Array of local memory page types, NULL if no local memory and page_types is 0.

    -

    The array is sorted by increasing size fields. It contains page_types_len slots.

    -

    Field Documentation

    - -

    ◆ count

    - -
    -
    - - - - -
    hwloc_uint64_t hwloc_obj_attr_u::hwloc_numanode_attr_s::hwloc_memory_page_type_s::count
    -
    - -

    Number of pages of this size.

    - -
    -
    - -

    ◆ size

    - -
    -
    - - - - -
    hwloc_uint64_t hwloc_obj_attr_u::hwloc_numanode_attr_s::hwloc_memory_page_type_s::size
    -
    - -

    Size of pages.

    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - - -
    -
    -Data Fields
    -
    hwloc_obj_attr_u::hwloc_cache_attr_s Struct Reference
    -
    -
    - -

    #include <hwloc.h>

    - - - - - - - - - - - - -

    -Data Fields

    hwloc_uint64_t size
     
    unsigned depth
     
    unsigned linesize
     
    int associativity
     
    hwloc_obj_cache_type_t type
     
    -

    Detailed Description

    -

    Cache-specific Object Attributes.

    -

    Field Documentation

    - -

    ◆ associativity

    - -
    -
    - - - - -
    int hwloc_obj_attr_u::hwloc_cache_attr_s::associativity
    -
    - -

    Ways of associativity, -1 if fully associative, 0 if unknown.

    - -
    -
    - -

    ◆ depth

    - -
    -
    - - - - -
    unsigned hwloc_obj_attr_u::hwloc_cache_attr_s::depth
    -
    - -

    Depth of cache (e.g., L1, L2, ...etc.)

    - -
    -
    - -

    ◆ linesize

    - -
    -
    - - - - -
    unsigned hwloc_obj_attr_u::hwloc_cache_attr_s::linesize
    -
    - -

    Cache-line size in bytes. 0 if unknown.

    - -
    -
    - -

    ◆ size

    - -
    -
    - - - - -
    hwloc_uint64_t hwloc_obj_attr_u::hwloc_cache_attr_s::size
    -
    - -

    Size of cache in bytes.

    - -
    -
    - -

    ◆ type

    - -
    -
    - - - - -
    hwloc_obj_cache_type_t hwloc_obj_attr_u::hwloc_cache_attr_s::type
    -
    - -

    Cache type.

    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - - -
    -
    -Data Fields
    -
    hwloc_obj_attr_u::hwloc_group_attr_s Struct Reference
    -
    -
    - -

    #include <hwloc.h>

    - - - - - - - - - - -

    -Data Fields

    unsigned depth
     
    unsigned kind
     
    unsigned subkind
     
    unsigned char dont_merge
     
    -

    Detailed Description

    -

    Group-specific Object Attributes.

    -

    Field Documentation

    - -

    ◆ depth

    - -
    -
    - - - - -
    unsigned hwloc_obj_attr_u::hwloc_group_attr_s::depth
    -
    - -

    Depth of group object. It may change if intermediate Group objects are added.

    - -
    -
    - -

    ◆ dont_merge

    - -
    -
    - - - - -
    unsigned char hwloc_obj_attr_u::hwloc_group_attr_s::dont_merge
    -
    - -

    Flag preventing groups from being automatically merged with identical parent or children.

    - -
    -
    - -

    ◆ kind

    - -
    -
    - - - - -
    unsigned hwloc_obj_attr_u::hwloc_group_attr_s::kind
    -
    - -

    Internally-used kind of group.

    - -
    -
    - -

    ◆ subkind

    - -
    -
    - - - - -
    unsigned hwloc_obj_attr_u::hwloc_group_attr_s::subkind
    -
    - -

    Internally-used subkind to distinguish different levels of groups with same kind.

    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - - -
    -
    -Data Fields
    -
    hwloc_obj_attr_u::hwloc_pcidev_attr_s Struct Reference
    -
    -
    - -

    #include <hwloc.h>

    - - - - - - - - - - - - - - - - - - - - - - - - -

    -Data Fields

    unsigned short domain
     
    unsigned char bus
     
    unsigned char dev
     
    unsigned char func
     
    unsigned short class_id
     
    unsigned short vendor_id
     
    unsigned short device_id
     
    unsigned short subvendor_id
     
    unsigned short subdevice_id
     
    unsigned char revision
     
    float linkspeed
     
    -

    Detailed Description

    -

    PCI Device specific Object Attributes.

    -

    Field Documentation

    - -

    ◆ bus

    - -
    -
    - - - - -
    unsigned char hwloc_obj_attr_u::hwloc_pcidev_attr_s::bus
    -
    - -
    -
    - -

    ◆ class_id

    - -
    -
    - - - - -
    unsigned short hwloc_obj_attr_u::hwloc_pcidev_attr_s::class_id
    -
    - -
    -
    - -

    ◆ dev

    - -
    -
    - - - - -
    unsigned char hwloc_obj_attr_u::hwloc_pcidev_attr_s::dev
    -
    - -
    -
    - -

    ◆ device_id

    - -
    -
    - - - - -
    unsigned short hwloc_obj_attr_u::hwloc_pcidev_attr_s::device_id
    -
    - -
    -
    - -

    ◆ domain

    - -
    -
    - - - - -
    unsigned short hwloc_obj_attr_u::hwloc_pcidev_attr_s::domain
    -
    - -
    -
    - -

    ◆ func

    - -
    -
    - - - - -
    unsigned char hwloc_obj_attr_u::hwloc_pcidev_attr_s::func
    -
    - -
    -
    - -

    ◆ linkspeed

    - -
    -
    - - - - -
    float hwloc_obj_attr_u::hwloc_pcidev_attr_s::linkspeed
    -
    - -
    -
    - -

    ◆ revision

    - -
    -
    - - - - -
    unsigned char hwloc_obj_attr_u::hwloc_pcidev_attr_s::revision
    -
    - -
    -
    - -

    ◆ subdevice_id

    - -
    -
    - - - - -
    unsigned short hwloc_obj_attr_u::hwloc_pcidev_attr_s::subdevice_id
    -
    - -
    -
    - -

    ◆ subvendor_id

    - -
    -
    - - - - -
    unsigned short hwloc_obj_attr_u::hwloc_pcidev_attr_s::subvendor_id
    -
    - -
    -
    - -

    ◆ vendor_id

    - -
    -
    - - - - -
    unsigned short hwloc_obj_attr_u::hwloc_pcidev_attr_s::vendor_id
    -
    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - - -
    -
    -Data Fields
    -
    hwloc_obj_attr_u::hwloc_bridge_attr_s Struct Reference
    -
    -
    - -

    #include <hwloc.h>

    - - - - - - - - - - - - - - - - - - - - - - - - - -

    -Data Fields

    union {
       struct hwloc_pcidev_attr_s   pci
     
    } upstream
     
    hwloc_obj_bridge_type_t upstream_type
     
    union {
       struct {
          unsigned short   domain
     
          unsigned char   secondary_bus
     
          unsigned char   subordinate_bus
     
       }   pci
     
    } downstream
     
    hwloc_obj_bridge_type_t downstream_type
     
    unsigned depth
     
    -

    Detailed Description

    -

    Bridge specific Object Attributes.

    -

    Field Documentation

    - -

    ◆ depth

    - -
    -
    - - - - -
    unsigned hwloc_obj_attr_u::hwloc_bridge_attr_s::depth
    -
    - -
    -
    - -

    ◆ domain

    - -
    -
    - - - - -
    unsigned short hwloc_obj_attr_u::hwloc_bridge_attr_s::domain
    -
    - -
    -
    - -

    ◆ 

    - -
    -
    - - - - -
    union { ... } hwloc_obj_attr_u::hwloc_bridge_attr_s::downstream
    -
    - -
    -
    - -

    ◆ downstream_type

    - -
    -
    - - - - -
    hwloc_obj_bridge_type_t hwloc_obj_attr_u::hwloc_bridge_attr_s::downstream_type
    -
    - -
    -
    - -

    ◆ pci [1/2]

    - -
    -
    - - - - -
    struct hwloc_pcidev_attr_s hwloc_obj_attr_u::hwloc_bridge_attr_s::pci
    -
    - -
    -
    - -

    ◆  [2/2]

    - -
    -
    - - - - -
    struct { ... } hwloc_obj_attr_u::hwloc_bridge_attr_s::pci
    -
    - -
    -
    - -

    ◆ secondary_bus

    - -
    -
    - - - - -
    unsigned char hwloc_obj_attr_u::hwloc_bridge_attr_s::secondary_bus
    -
    - -
    -
    - -

    ◆ subordinate_bus

    - -
    -
    - - - - -
    unsigned char hwloc_obj_attr_u::hwloc_bridge_attr_s::subordinate_bus
    -
    - -
    -
    - -

    ◆ 

    - -
    -
    - - - - -
    union { ... } hwloc_obj_attr_u::hwloc_bridge_attr_s::upstream
    -
    - -
    -
    - -

    ◆ upstream_type

    - -
    -
    - - - - -
    hwloc_obj_bridge_type_t hwloc_obj_attr_u::hwloc_bridge_attr_s::upstream_type
    -
    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - - -
    -
    -Data Fields
    -
    hwloc_obj_attr_u::hwloc_osdev_attr_s Struct Reference
    -
    -
    - -

    #include <hwloc.h>

    - - - - -

    -Data Fields

    hwloc_obj_osdev_type_t type
     
    -

    Detailed Description

    -

    OS Device specific Object Attributes.

    -

    Field Documentation

    - -

    ◆ type

    - -
    -
    - - - - -
    hwloc_obj_osdev_type_t hwloc_obj_attr_u::hwloc_osdev_attr_s::type
    -
    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - -
    -
    -Data Fields
    -
    hwloc_info_s Struct Reference
    Object Structure and Attributes
    -
    -
    - -

    #include <hwloc.h>

    - - - - - - -

    -Data Fields

    char * name
     
    char * value
     
    -

    Detailed Description

    -

    Object info.

    -
    See also
    Consulting and Adding Key-Value Info Attributes
    -

    Field Documentation

    - -

    ◆ name

    - -
    -
    - - - - -
    char* hwloc_info_s::name
    -
    - -

    Info name.

    - -
    -
    - -

    ◆ value

    - -
    -
    - - - - -
    char* hwloc_info_s::value
    -
    - -

    Info value.

    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - -
    -
    -Data Fields
    -
    hwloc_topology_discovery_support Struct Reference
    Topology Detection Configuration and Query
    -
    -
    - -

    #include <hwloc.h>

    - - - - - - - - - - - - - - -

    -Data Fields

    unsigned char pu
     
    unsigned char numa
     
    unsigned char numa_memory
     
    unsigned char disallowed_pu
     
    unsigned char disallowed_numa
     
    unsigned char cpukind_efficiency
     
    -

    Detailed Description

    -

    Flags describing actual discovery support for this topology.

    -

    Field Documentation

    - -

    ◆ cpukind_efficiency

    - -
    -
    - - - - -
    unsigned char hwloc_topology_discovery_support::cpukind_efficiency
    -
    - -

    Detecting the efficiency of CPU kinds is supported, see Kinds of CPU cores.

    - -
    -
    - -

    ◆ disallowed_numa

    - -
    -
    - - - - -
    unsigned char hwloc_topology_discovery_support::disallowed_numa
    -
    - -

    Detecting and identifying NUMA nodes that are not available to the current process is supported.

    - -
    -
    - -

    ◆ disallowed_pu

    - -
    -
    - - - - -
    unsigned char hwloc_topology_discovery_support::disallowed_pu
    -
    - -

    Detecting and identifying PU objects that are not available to the current process is supported.

    - -
    -
    - -

    ◆ numa

    - -
    -
    - - - - -
    unsigned char hwloc_topology_discovery_support::numa
    -
    - -

    Detecting the number of NUMA nodes is supported.

    - -
    -
    - -

    ◆ numa_memory

    - -
    -
    - - - - -
    unsigned char hwloc_topology_discovery_support::numa_memory
    -
    - -

    Detecting the amount of memory in NUMA nodes is supported.

    - -
    -
    - -

    ◆ pu

    - -
    -
    - - - - -
    unsigned char hwloc_topology_discovery_support::pu
    -
    - -

    Detecting the number of PU objects is supported.

    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - -
    -
    -Data Fields
    -
    hwloc_topology_cpubind_support Struct Reference
    Topology Detection Configuration and Query
    -
    -
    - -

    #include <hwloc.h>

    - - - - - - - - - - - - - - - - - - - - - - - - -

    -Data Fields

    unsigned char set_thisproc_cpubind
     
    unsigned char get_thisproc_cpubind
     
    unsigned char set_proc_cpubind
     
    unsigned char get_proc_cpubind
     
    unsigned char set_thisthread_cpubind
     
    unsigned char get_thisthread_cpubind
     
    unsigned char set_thread_cpubind
     
    unsigned char get_thread_cpubind
     
    unsigned char get_thisproc_last_cpu_location
     
    unsigned char get_proc_last_cpu_location
     
    unsigned char get_thisthread_last_cpu_location
     
    -

    Detailed Description

    -

    Flags describing actual PU binding support for this topology.

    -

    A flag may be set even if the feature isn't supported in all cases (e.g. binding to random sets of non-contiguous objects).

    -

    Field Documentation

    - -

    ◆ get_proc_cpubind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_cpubind_support::get_proc_cpubind
    -
    -

    Getting the binding of a whole given process is supported.

    - -
    -
    - -

    ◆ get_proc_last_cpu_location

    - -
    -
    - - - - -
    unsigned char hwloc_topology_cpubind_support::get_proc_last_cpu_location
    -
    -

    Getting the last processors where a whole process ran is supported

    - -
    -
    - -

    ◆ get_thisproc_cpubind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_cpubind_support::get_thisproc_cpubind
    -
    -

    Getting the binding of the whole current process is supported.

    - -
    -
    - -

    ◆ get_thisproc_last_cpu_location

    - -
    -
    - - - - -
    unsigned char hwloc_topology_cpubind_support::get_thisproc_last_cpu_location
    -
    -

    Getting the last processors where the whole current process ran is supported

    - -
    -
    - -

    ◆ get_thisthread_cpubind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_cpubind_support::get_thisthread_cpubind
    -
    -

    Getting the binding of the current thread only is supported.

    - -
    -
    - -

    ◆ get_thisthread_last_cpu_location

    - -
    -
    - - - - -
    unsigned char hwloc_topology_cpubind_support::get_thisthread_last_cpu_location
    -
    -

    Getting the last processors where the current thread ran is supported

    - -
    -
    - -

    ◆ get_thread_cpubind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_cpubind_support::get_thread_cpubind
    -
    -

    Getting the binding of a given thread only is supported.

    - -
    -
    - -

    ◆ set_proc_cpubind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_cpubind_support::set_proc_cpubind
    -
    -

    Binding a whole given process is supported.

    - -
    -
    - -

    ◆ set_thisproc_cpubind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_cpubind_support::set_thisproc_cpubind
    -
    -

    Binding the whole current process is supported.

    - -
    -
    - -

    ◆ set_thisthread_cpubind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_cpubind_support::set_thisthread_cpubind
    -
    -

    Binding the current thread only is supported.

    - -
    -
    - -

    ◆ set_thread_cpubind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_cpubind_support::set_thread_cpubind
    -
    -

    Binding a given thread only is supported.

    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - -
    -
    -Data Fields
    -
    hwloc_topology_membind_support Struct Reference
    Topology Detection Configuration and Query
    -
    -
    - -

    #include <hwloc.h>

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

    -Data Fields

    unsigned char set_thisproc_membind
     
    unsigned char get_thisproc_membind
     
    unsigned char set_proc_membind
     
    unsigned char get_proc_membind
     
    unsigned char set_thisthread_membind
     
    unsigned char get_thisthread_membind
     
    unsigned char set_area_membind
     
    unsigned char get_area_membind
     
    unsigned char alloc_membind
     
    unsigned char firsttouch_membind
     
    unsigned char bind_membind
     
    unsigned char interleave_membind
     
    unsigned char nexttouch_membind
     
    unsigned char migrate_membind
     
    unsigned char get_area_memlocation
     
    -

    Detailed Description

    -

    Flags describing actual memory binding support for this topology.

    -

    A flag may be set even if the feature isn't supported in all cases (e.g. binding to random sets of non-contiguous objects).

    -

    Field Documentation

    - -

    ◆ alloc_membind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_membind_support::alloc_membind
    -
    -

    Allocating a bound memory area is supported.

    - -
    -
    - -

    ◆ bind_membind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_membind_support::bind_membind
    -
    -

    Bind policy is supported.

    - -
    -
    - -

    ◆ firsttouch_membind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_membind_support::firsttouch_membind
    -
    -

    First-touch policy is supported.

    - -
    -
    - -

    ◆ get_area_membind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_membind_support::get_area_membind
    -
    -

    Getting the binding of a given memory area is supported.

    - -
    -
    - -

    ◆ get_area_memlocation

    - -
    -
    - - - - -
    unsigned char hwloc_topology_membind_support::get_area_memlocation
    -
    -

    Getting the last NUMA nodes where a memory area was allocated is supported

    - -
    -
    - -

    ◆ get_proc_membind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_membind_support::get_proc_membind
    -
    -

    Getting the binding of a whole given process is supported.

    - -
    -
    - -

    ◆ get_thisproc_membind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_membind_support::get_thisproc_membind
    -
    -

    Getting the binding of the whole current process is supported.

    - -
    -
    - -

    ◆ get_thisthread_membind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_membind_support::get_thisthread_membind
    -
    -

    Getting the binding of the current thread only is supported.

    - -
    -
    - -

    ◆ interleave_membind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_membind_support::interleave_membind
    -
    -

    Interleave policy is supported.

    - -
    -
    - -

    ◆ migrate_membind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_membind_support::migrate_membind
    -
    -

    Migration flags is supported.

    - -
    -
    - -

    ◆ nexttouch_membind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_membind_support::nexttouch_membind
    -
    -

    Next-touch migration policy is supported.

    - -
    -
    - -

    ◆ set_area_membind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_membind_support::set_area_membind
    -
    -

    Binding a given memory area is supported.

    - -
    -
    - -

    ◆ set_proc_membind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_membind_support::set_proc_membind
    -
    -

    Binding a whole given process is supported.

    - -
    -
    - -

    ◆ set_thisproc_membind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_membind_support::set_thisproc_membind
    -
    -

    Binding the whole current process is supported.

    - -
    -
    - -

    ◆ set_thisthread_membind

    - -
    -
    - - - - -
    unsigned char hwloc_topology_membind_support::set_thisthread_membind
    -
    -

    Binding the current thread only is supported.

    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - -
    -
    -Data Fields
    -
    hwloc_topology_misc_support Struct Reference
    Topology Detection Configuration and Query
    -
    -
    - -

    #include <hwloc.h>

    - - - - -

    -Data Fields

    unsigned char imported_support
     
    -

    Detailed Description

    -

    Flags describing miscellaneous features.

    -

    Field Documentation

    - -

    ◆ imported_support

    - -
    -
    - - - - -
    unsigned char hwloc_topology_misc_support::imported_support
    -
    -

    Support was imported when importing another topology, see HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT.

    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - -
    -
    -Data Fields
    -
    hwloc_topology_support Struct Reference
    Topology Detection Configuration and Query
    -
    -
    - -

    #include <hwloc.h>

    - - - - - - - - - - -

    -Data Fields

    struct hwloc_topology_discovery_support * discovery
     
    struct hwloc_topology_cpubind_support * cpubind
     
    struct hwloc_topology_membind_support * membind
     
    struct hwloc_topology_misc_support * misc
     
    -

    Detailed Description

    -

    Set of flags describing actual support for this topology.

    -

    This is retrieved with hwloc_topology_get_support() and will be valid until the topology object is destroyed. Note: the values are correct only after discovery.

    -

    Field Documentation

    - -

    ◆ cpubind

    - -
    -
    - - - - -
    struct hwloc_topology_cpubind_support* hwloc_topology_support::cpubind
    -
    - -
    -
    - -

    ◆ discovery

    - -
    -
    - - - - -
    struct hwloc_topology_discovery_support* hwloc_topology_support::discovery
    -
    - -
    -
    - -

    ◆ membind

    - -
    -
    - - - - -
    struct hwloc_topology_membind_support* hwloc_topology_support::membind
    -
    - -
    -
    - -

    ◆ misc

    - -
    -
    - - - - -
    struct hwloc_topology_misc_support* hwloc_topology_support::misc
    -
    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - -
    -
    -Data Fields
    -
    hwloc_distances_s Struct Reference
    Retrieve distances between objects
    -
    -
    - -

    #include <distances.h>

    - - - - - - - - - - -

    -Data Fields

    unsigned nbobjs
     
    hwloc_obj_t * objs
     
    unsigned long kind
     
    hwloc_uint64_t * values
     
    -

    Detailed Description

    -

    Matrix of distances between a set of objects.

    -

    This matrix often contains latencies between NUMA nodes (as reported in the System Locality Distance Information Table (SLIT) in the ACPI specification), which may or may not be physically accurate. It corresponds to the latency for accessing the memory of one node from a core in another node. The corresponding kind is HWLOC_DISTANCES_KIND_FROM_OS | HWLOC_DISTANCES_KIND_FROM_USER. The name of this distances structure is "NUMALatency". Others distance structures include and "XGMIBandwidth", "XGMIHops", "XeLinkBandwidth" and "NVLinkBandwidth".

    -

    The matrix may also contain bandwidths between random sets of objects, possibly provided by the user, as specified in the kind attribute.

    -

    Pointers objs and values should not be replaced, reallocated, freed, etc. However callers are allowed to modify kind as well as the contents of objs and values arrays. For instance, if there is a single NUMA node per Package, hwloc_get_obj_with_same_locality() may be used to convert between them and replace NUMA nodes in the objs array with the corresponding Packages. See also hwloc_distances_transform() for applying some transformations to the structure.

    -

    Field Documentation

    - -

    ◆ kind

    - -
    -
    - - - - -
    unsigned long hwloc_distances_s::kind
    -
    - -

    OR'ed set of hwloc_distances_kind_e.

    - -
    -
    - -

    ◆ nbobjs

    - -
    -
    - - - - -
    unsigned hwloc_distances_s::nbobjs
    -
    - -

    Number of objects described by the distance matrix.

    - -
    -
    - -

    ◆ objs

    - -
    -
    - - - - -
    hwloc_obj_t* hwloc_distances_s::objs
    -
    - -

    Array of objects described by the distance matrix. These objects are not in any particular order, see hwloc_distances_obj_index() and hwloc_distances_obj_pair_values() for easy ways to find objects in this array and their corresponding values.

    - -
    -
    - -

    ◆ values

    - -
    -
    - - - - -
    hwloc_uint64_t* hwloc_distances_s::values
    -
    - -

    Matrix of distances between objects, stored as a one-dimension array.

    -

    Distance from i-th to j-th object is stored in slot i*nbobjs+j. The meaning of the value depends on the kind attribute.

    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - -
    -
    -Data Structures | -Data Fields
    -
    hwloc_location Struct Reference
    Comparing memory node attributes for finding where to allocate on
    -
    -
    - -

    #include <memattrs.h>

    - - - - -

    -Data Structures

    union  hwloc_location_u
     
    - - - - - -

    -Data Fields

    enum hwloc_location_type_e type
     
    union hwloc_location::hwloc_location_u location
     
    -

    Detailed Description

    -

    Where to measure attributes from.

    -

    Field Documentation

    - -

    ◆ location

    - -
    -
    - - - - -
    union hwloc_location::hwloc_location_u hwloc_location::location
    -
    - -
    -
    - -

    ◆ type

    - -
    -
    - - - - -
    enum hwloc_location_type_e hwloc_location::type
    -
    - -

    Type of location.

    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - - -
    -
    -Data Fields
    -
    hwloc_location::hwloc_location_u Union Reference
    -
    -
    - -

    #include <memattrs.h>

    - - - - - - -

    -Data Fields

    hwloc_cpuset_t cpuset
     
    hwloc_obj_t object
     
    -

    Detailed Description

    -

    Actual location.

    -

    Field Documentation

    - -

    ◆ cpuset

    - -
    -
    - - - - -
    hwloc_cpuset_t hwloc_location::hwloc_location_u::cpuset
    -
    - -

    Location as a cpuset, when the location type is HWLOC_LOCATION_TYPE_CPUSET.

    - -
    -
    - -

    ◆ object

    - -
    -
    - - - - -
    hwloc_obj_t hwloc_location::hwloc_location_u::object
    -
    - -

    Location as an object, when the location type is HWLOC_LOCATION_TYPE_OBJECT.

    - -
    -
    -
    The documentation for this union was generated from the following file: -
    - - - - - - - -
    -
    -Data Fields
    -
    hwloc_cl_device_topology_amd Union Reference
    -
    -
    - -

    #include <opencl.h>

    - - - - - - - - - - - - - - - - - - - - - - -

    -Data Fields

    struct {
       cl_uint   type
     
       cl_uint   data [5]
     
    } raw
     
    struct {
       cl_uint   type
     
       cl_char   unused [17]
     
       cl_char   bus
     
       cl_char   device
     
       cl_char   function
     
    } pcie
     
    -

    Field Documentation

    - -

    ◆ bus

    - -
    -
    - - - - -
    cl_char hwloc_cl_device_topology_amd::bus
    -
    - -
    -
    - -

    ◆ data

    - -
    -
    - - - - -
    cl_uint hwloc_cl_device_topology_amd::data[5]
    -
    - -
    -
    - -

    ◆ device

    - -
    -
    - - - - -
    cl_char hwloc_cl_device_topology_amd::device
    -
    - -
    -
    - -

    ◆ function

    - -
    -
    - - - - -
    cl_char hwloc_cl_device_topology_amd::function
    -
    - -
    -
    - -

    ◆ 

    - -
    -
    - - - - -
    struct { ... } hwloc_cl_device_topology_amd::pcie
    -
    - -
    -
    - -

    ◆ 

    - -
    -
    - - - - -
    struct { ... } hwloc_cl_device_topology_amd::raw
    -
    - -
    -
    - -

    ◆ type

    - -
    -
    - - - - -
    cl_uint hwloc_cl_device_topology_amd::type
    -
    - -
    -
    - -

    ◆ unused

    - -
    -
    - - - - -
    cl_char hwloc_cl_device_topology_amd::unused[17]
    -
    - -
    -
    -
    The documentation for this union was generated from the following file: -
    - - - - - - - -
    -
    -Data Structures | -Data Fields
    -
    hwloc_topology_diff_obj_attr_u Union Reference
    Topology differences
    -
    -
    - -

    #include <diff.h>

    - - - - - - - - -

    -Data Structures

    struct  hwloc_topology_diff_obj_attr_generic_s
     
    struct  hwloc_topology_diff_obj_attr_string_s
     
    struct  hwloc_topology_diff_obj_attr_uint64_s
     
    - - - - - - - -

    -Data Fields

    struct hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_generic_s generic
     
    struct hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s uint64
     
    struct hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s string
     
    -

    Detailed Description

    -

    One object attribute difference.

    -

    Field Documentation

    - -

    ◆ generic

    - -
    -
    - - - - -
    struct hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_generic_s hwloc_topology_diff_obj_attr_u::generic
    -
    - -
    -
    - -

    ◆ string

    - -
    -
    - - - - -
    struct hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s hwloc_topology_diff_obj_attr_u::string
    -
    - -
    -
    - -

    ◆ uint64

    - -
    -
    - - - - -
    struct hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s hwloc_topology_diff_obj_attr_u::uint64
    -
    - -
    -
    -
    The documentation for this union was generated from the following file: -
    - - - - - - - - -
    -
    -Data Fields
    -
    hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_generic_s Struct Reference
    -
    -
    - -

    #include <diff.h>

    - - - - -

    -Data Fields

    hwloc_topology_diff_obj_attr_type_t type
     
    -

    Field Documentation

    - -

    ◆ type

    - -
    -
    - - - - -
    hwloc_topology_diff_obj_attr_type_t hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_generic_s::type
    -
    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - - -
    -
    -Data Fields
    -
    hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s Struct Reference
    -
    -
    - -

    #include <diff.h>

    - - - - - - - - - - -

    -Data Fields

    hwloc_topology_diff_obj_attr_type_t type
     
    hwloc_uint64_t index
     
    hwloc_uint64_t oldvalue
     
    hwloc_uint64_t newvalue
     
    -

    Detailed Description

    -

    Integer attribute modification with an optional index.

    -

    Field Documentation

    - -

    ◆ index

    - -
    -
    - - - - -
    hwloc_uint64_t hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s::index
    -
    - -
    -
    - -

    ◆ newvalue

    - -
    -
    - - - - -
    hwloc_uint64_t hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s::newvalue
    -
    - -
    -
    - -

    ◆ oldvalue

    - -
    -
    - - - - -
    hwloc_uint64_t hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s::oldvalue
    -
    - -
    -
    - -

    ◆ type

    - -
    -
    - - - - -
    hwloc_topology_diff_obj_attr_type_t hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s::type
    -
    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - - -
    -
    -Data Fields
    -
    hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s Struct Reference
    -
    -
    - -

    #include <diff.h>

    - - - - - - - - - - -

    -Data Fields

    hwloc_topology_diff_obj_attr_type_t type
     
    char * name
     
    char * oldvalue
     
    char * newvalue
     
    -

    Detailed Description

    -

    String attribute modification with an optional name.

    -

    Field Documentation

    - -

    ◆ name

    - -
    -
    - - - - -
    char* hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s::name
    -
    - -
    -
    - -

    ◆ newvalue

    - -
    -
    - - - - -
    char* hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s::newvalue
    -
    - -
    -
    - -

    ◆ oldvalue

    - -
    -
    - - - - -
    char* hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s::oldvalue
    -
    - -
    -
    - -

    ◆ type

    - -
    -
    - - - - -
    hwloc_topology_diff_obj_attr_type_t hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s::type
    -
    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - -
    -
    -Data Structures | -Data Fields
    -
    hwloc_topology_diff_u Union Reference
    Topology differences
    -
    -
    - -

    #include <diff.h>

    - - - - - - - - -

    -Data Structures

    struct  hwloc_topology_diff_generic_s
     
    struct  hwloc_topology_diff_obj_attr_s
     
    struct  hwloc_topology_diff_too_complex_s
     
    - - - - - - - -

    -Data Fields

    struct hwloc_topology_diff_u::hwloc_topology_diff_generic_s generic
     
    struct hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s obj_attr
     
    struct hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s too_complex
     
    -

    Detailed Description

    -

    One element of a difference list between two topologies.

    -

    Field Documentation

    - -

    ◆ generic

    - -
    -
    - - - - -
    struct hwloc_topology_diff_u::hwloc_topology_diff_generic_s hwloc_topology_diff_u::generic
    -
    - -
    -
    - -

    ◆ obj_attr

    - -
    -
    - - - - -
    struct hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s hwloc_topology_diff_u::obj_attr
    -
    - -
    -
    - -

    ◆ too_complex

    - -
    -
    - - - - -
    struct hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s hwloc_topology_diff_u::too_complex
    -
    - -
    -
    -
    The documentation for this union was generated from the following file: -
    - - - - - - - - -
    -
    -Data Fields
    -
    hwloc_topology_diff_u::hwloc_topology_diff_generic_s Struct Reference
    -
    -
    - -

    #include <diff.h>

    - - - - - - -

    -Data Fields

    hwloc_topology_diff_type_t type
     
    union hwloc_topology_diff_u * next
     
    -

    Field Documentation

    - -

    ◆ next

    - -
    -
    - - - - -
    union hwloc_topology_diff_u* hwloc_topology_diff_u::hwloc_topology_diff_generic_s::next
    -
    - -
    -
    - -

    ◆ type

    - -
    -
    - - - - -
    hwloc_topology_diff_type_t hwloc_topology_diff_u::hwloc_topology_diff_generic_s::type
    -
    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - - -
    -
    -Data Fields
    -
    hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s Struct Reference
    -
    -
    - -

    #include <diff.h>

    - - - - - - - - - - - - -

    -Data Fields

    hwloc_topology_diff_type_t type
     
    union hwloc_topology_diff_u * next
     
    int obj_depth
     
    unsigned obj_index
     
    union hwloc_topology_diff_obj_attr_u diff
     
    -

    Field Documentation

    - -

    ◆ diff

    - -
    -
    - - - - -
    union hwloc_topology_diff_obj_attr_u hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s::diff
    -
    - -
    -
    - -

    ◆ next

    - -
    -
    - - - - -
    union hwloc_topology_diff_u* hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s::next
    -
    - -
    -
    - -

    ◆ obj_depth

    - -
    -
    - - - - -
    int hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s::obj_depth
    -
    - -
    -
    - -

    ◆ obj_index

    - -
    -
    - - - - -
    unsigned hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s::obj_index
    -
    - -
    -
    - -

    ◆ type

    - -
    -
    - - - - -
    hwloc_topology_diff_type_t hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s::type
    -
    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - - -
    -
    -Data Fields
    -
    hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s Struct Reference
    -
    -
    - -

    #include <diff.h>

    - - - - - - - - - - -

    -Data Fields

    hwloc_topology_diff_type_t type
     
    union hwloc_topology_diff_u * next
     
    int obj_depth
     
    unsigned obj_index
     
    -

    Field Documentation

    - -

    ◆ next

    - -
    -
    - - - - -
    union hwloc_topology_diff_u* hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s::next
    -
    - -
    -
    - -

    ◆ obj_depth

    - -
    -
    - - - - -
    int hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s::obj_depth
    -
    - -
    -
    - -

    ◆ obj_index

    - -
    -
    - - - - -
    unsigned hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s::obj_index
    -
    - -
    -
    - -

    ◆ type

    - -
    -
    - - - - -
    hwloc_topology_diff_type_t hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s::type
    -
    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - -
    -
    -Data Fields
    -
    hwloc_disc_component Struct Reference
    Components and Plugins: Discovery components
    -
    -
    - -

    #include <plugins.h>

    - - - - - - - - - - - - - - -

    -Data Fields

    const char * name
     
    unsigned phases
     
    unsigned excluded_phases
     
    struct hwloc_backend *(* instantiate )(struct hwloc_topology *topology, struct hwloc_disc_component *component, unsigned excluded_phases, const void *data1, const void *data2, const void *data3)
     
    unsigned priority
     
    unsigned enabled_by_default
     
    -

    Detailed Description

    -

    Discovery component structure.

    -

    This is the major kind of components, taking care of the discovery. They are registered by generic components, either statically-built or as plugins.

    -

    Field Documentation

    - -

    ◆ enabled_by_default

    - -
    -
    - - - - -
    unsigned hwloc_disc_component::enabled_by_default
    -
    - -

    Enabled by default. If unset, if will be disabled unless explicitly requested.

    - -
    -
    - -

    ◆ excluded_phases

    - -
    -
    - - - - -
    unsigned hwloc_disc_component::excluded_phases
    -
    - -

    Component phases to exclude, as an OR'ed set of hwloc_disc_phase_t.

    -

    For a GLOBAL component, this usually includes all other phases (~UL).

    -

    Other components only exclude types that may bring conflicting topology information. MISC components should likely not be excluded since they usually bring non-primary additional information.

    - -
    -
    - -

    ◆ instantiate

    - -
    -
    - - - - -
    struct hwloc_backend *(* hwloc_disc_component::instantiate) (struct hwloc_topology *topology, struct hwloc_disc_component *component, unsigned excluded_phases, const void *data1, const void *data2, const void *data3)
    -
    - -

    Instantiate callback to create a backend from the component. Parameters data1, data2, data3 are NULL except for components that have special enabling routines such as hwloc_topology_set_xml().

    - -
    -
    - -

    ◆ name

    - -
    -
    - - - - -
    const char* hwloc_disc_component::name
    -
    - -

    Name. If this component is built as a plugin, this name does not have to match the plugin filename.

    - -
    -
    - -

    ◆ phases

    - -
    -
    - - - - -
    unsigned hwloc_disc_component::phases
    -
    - -

    Discovery phases performed by this component. OR'ed set of hwloc_disc_phase_t.

    - -
    -
    - -

    ◆ priority

    - -
    -
    - - - - -
    unsigned hwloc_disc_component::priority
    -
    - -

    Component priority. Used to sort topology->components, higher priority first. Also used to decide between two components with the same name.

    -

    Usual values are 50 for native OS (or platform) components, 45 for x86, 40 for no-OS fallback, 30 for global components (xml, synthetic), 20 for pci, 10 for other misc components (opencl etc.).

    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - -
    -
    -Data Fields
    -
    hwloc_disc_status Struct Reference
    Components and Plugins: Discovery backends
    -
    -
    - -

    #include <plugins.h>

    - - - - - - - - -

    -Data Fields

    hwloc_disc_phase_t phase
     
    unsigned excluded_phases
     
    unsigned long flags
     
    -

    Detailed Description

    -

    Discovery status structure.

    -

    Used by the core and backends to inform about what has been/is being done during the discovery process.

    -

    Field Documentation

    - -

    ◆ excluded_phases

    - -
    -
    - - - - -
    unsigned hwloc_disc_status::excluded_phases
    -
    - -

    Dynamically excluded phases. If a component decides during discovery that some phases are no longer needed.

    - -
    -
    - -

    ◆ flags

    - -
    -
    - - - - -
    unsigned long hwloc_disc_status::flags
    -
    - -

    OR'ed set of hwloc_disc_status_flag_e.

    - -
    -
    - -

    ◆ phase

    - -
    -
    - - - - -
    hwloc_disc_phase_t hwloc_disc_status::phase
    -
    - -

    The current discovery phase that is performed. Must match one of the phases in the component phases field.

    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - -
    -
    -Data Fields
    -
    hwloc_backend Struct Reference
    Components and Plugins: Discovery backends
    -
    -
    - -

    #include <plugins.h>

    - - - - - - - - - - - - - - - - -

    -Data Fields

    unsigned phases
     
    unsigned long flags
     
    int is_thissystem
     
    void * private_data
     
    void(* disable )(struct hwloc_backend *backend)
     
    int(* discover )(struct hwloc_backend *backend, struct hwloc_disc_status *status)
     
    int(* get_pci_busid_cpuset )(struct hwloc_backend *backend, struct hwloc_pcidev_attr_s *busid, hwloc_bitmap_t cpuset)
     
    -

    Detailed Description

    -

    Discovery backend structure.

    -

    A backend is the instantiation of a discovery component. When a component gets enabled for a topology, its instantiate() callback creates a backend.

    -

    hwloc_backend_alloc() initializes all fields to default values that the component may change (except "component" and "next") before enabling the backend with hwloc_backend_enable().

    -

    Most backends assume that the topology is_thissystem flag is set because they talk to the underlying operating system. However they may still be used in topologies without the is_thissystem flag for debugging reasons. In practice, they are usually auto-disabled in such cases (excluded by xml or synthetic backends, or by environment variables when changing the Linux fsroot or the x86 cpuid path).

    -

    Field Documentation

    - -

    ◆ disable

    - -
    -
    - - - - -
    void(* hwloc_backend::disable) (struct hwloc_backend *backend)
    -
    - -

    Callback for freeing the private_data. May be NULL.

    - -
    -
    - -

    ◆ discover

    - -
    -
    - - - - -
    int(* hwloc_backend::discover) (struct hwloc_backend *backend, struct hwloc_disc_status *status)
    -
    - -

    Main discovery callback. returns -1 on error, either because it couldn't add its objects ot the existing topology, or because of an actual discovery/gathering failure. May be NULL.

    - -
    -
    - -

    ◆ flags

    - -
    -
    - - - - -
    unsigned long hwloc_backend::flags
    -
    - -

    Backend flags, currently always 0.

    - -
    -
    - -

    ◆ get_pci_busid_cpuset

    - -
    -
    - - - - -
    int(* hwloc_backend::get_pci_busid_cpuset) (struct hwloc_backend *backend, struct hwloc_pcidev_attr_s *busid, hwloc_bitmap_t cpuset)
    -
    - -

    Callback to retrieve the locality of a PCI object. Called by the PCI core when attaching PCI hierarchy to CPU objects. May be NULL.

    - -
    -
    - -

    ◆ is_thissystem

    - -
    -
    - - - - -
    int hwloc_backend::is_thissystem
    -
    - -

    Backend-specific 'is_thissystem' property. Set to 0 if the backend disables the thissystem flag for this topology (e.g. loading from xml or synthetic string, or using a different fsroot on Linux, or a x86 CPUID dump). Set to -1 if the backend doesn't care (default).

    - -
    -
    - -

    ◆ phases

    - -
    -
    - - - - -
    unsigned hwloc_backend::phases
    -
    - -

    Discovery phases performed by this component, possibly without some of them if excluded by other components. OR'ed set of hwloc_disc_phase_t.

    - -
    -
    - -

    ◆ private_data

    - -
    -
    - - - - -
    void* hwloc_backend::private_data
    -
    - -

    Backend private data, or NULL if none.

    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - -
    -
    -Data Fields
    -
    hwloc_component Struct Reference
    Components and Plugins: Generic components
    -
    -
    - -

    #include <plugins.h>

    - - - - - - - - - - - - - - -

    -Data Fields

    unsigned abi
     
    int(* init )(unsigned long flags)
     
    void(* finalize )(unsigned long flags)
     
    hwloc_component_type_t type
     
    unsigned long flags
     
    void * data
     
    -

    Detailed Description

    -

    Generic component structure.

    -

    Generic components structure, either statically listed by configure in static-components.h or dynamically loaded as a plugin.

    -

    Field Documentation

    - -

    ◆ abi

    - -
    -
    - - - - -
    unsigned hwloc_component::abi
    -
    - -

    Component ABI version, set to HWLOC_COMPONENT_ABI.

    - -
    -
    - -

    ◆ data

    - -
    -
    - - - - -
    void* hwloc_component::data
    -
    - -

    Component data, pointing to a struct hwloc_disc_component or struct hwloc_xml_component.

    - -
    -
    - -

    ◆ finalize

    - -
    -
    - - - - -
    void(* hwloc_component::finalize) (unsigned long flags)
    -
    - -

    Process-wide component termination callback.

    -

    This optional callback is called after unregistering the component from the hwloc core (before unloading the plugin).

    -

    flags is always 0 for now.

    -
    Note
    If the component uses ltdl for loading its own plugins, it should load/unload them only in init() and finalize(), to avoid race conditions with hwloc's use of ltdl.
    - -
    -
    - -

    ◆ flags

    - -
    -
    - - - - -
    unsigned long hwloc_component::flags
    -
    - -

    Component flags, unused for now.

    - -
    -
    - -

    ◆ init

    - -
    -
    - - - - -
    int(* hwloc_component::init) (unsigned long flags)
    -
    - -

    Process-wide component initialization callback.

    -

    This optional callback is called when the component is registered to the hwloc core (after loading the plugin).

    -

    When the component is built as a plugin, this callback should call hwloc_check_plugin_namespace() and return an negative error code on error.

    -

    flags is always 0 for now.

    -
    Returns
    0 on success, or a negative code on error.
    -
    Note
    If the component uses ltdl for loading its own plugins, it should load/unload them only in init() and finalize(), to avoid race conditions with hwloc's use of ltdl.
    - -
    -
    - -

    ◆ type

    - -
    -
    - - - - -
    hwloc_component_type_t hwloc_component::type
    -
    - -

    Component type.

    - -
    -
    -
    The documentation for this struct was generated from the following file: -
    - - - - - - - -
    -
    Hardware Locality (hwloc) Introduction
    -
    -
    -

    Portable abstraction of hierarchical architectures for high-performance computing

    -
    -

    -

    - See also Further Reading -or the Related pages tab above - for links to more sections about hwloc concepts. -
    -

    -

    -

    -

    -

    -hwloc Summary

    -

    hwloc provides command line tools and a C API to obtain the hierarchical map of key computing elements within a node, such as: NUMA memory nodes, shared caches, processor packages, dies and cores, processing units (logical processors or "threads") and even I/O devices. hwloc also gathers various attributes such as cache and memory information, and is portable across a variety of different operating systems and platforms.

    -

    hwloc primarily aims at helping high-performance computing (HPC) applications, but is also applicable to any project seeking to exploit code and/or data locality on modern computing platforms.

    -

    hwloc supports the following operating systems:

    -
      -
    • -Linux (with knowledge of cgroups and cpusets, memory targets/initiators, etc.) on all supported hardware, including Intel Xeon Phi, ScaleMP vSMP, and NumaScale NumaConnect.
      • -
    • -Solaris (with support for processor sets and logical domains)
      • -
    • -AIX
      • -
    • -Darwin / OS X
      • -
    • -FreeBSD and its variants (such as kFreeBSD/GNU)
      • -
    • -NetBSD
      • -
    • -HP-UX
      • -
    • -Microsoft Windows
      • -
    • -IBM BlueGene/Q Compute Node Kernel (CNK)
      • -
    -

    Since it uses standard Operating System information, hwloc's support is mostly independant from the processor type (x86, powerpc, ...) and just relies on the Operating System support. The main exception is BSD operating systems (NetBSD, FreeBSD, etc.) because they do not provide support topology information, hence hwloc uses an x86-only CPUID-based backend (which can be used for other OSes too, see the Components and plugins section).

    -

    To check whether hwloc works on a particular machine, just try to build it and run lstopo or lstopo-no-graphics. If some things do not look right (e.g. bogus or missing cache information), see Questions and Bugs.

    -

    hwloc only reports the number of processors on unsupported operating systems; no topology information is available.

    -

    For development and debugging purposes, hwloc also offers the ability to work on "fake" topologies:

    - -

    hwloc can display the topology in a human-readable format, either in graphical mode (X11), or by exporting in one of several different formats, including: plain text, LaTeX tikzpicture, PDF, PNG, and FIG (see Command-line Examples below). Note that some of the export formats require additional support libraries.

    -

    hwloc offers a programming interface for manipulating topologies and objects. It also brings a powerful CPU bitmap API that is used to describe topology objects location on physical/logical processors. See the Programming Interface below. It may also be used to binding applications onto certain cores or memory nodes. Several utility programs are also provided to ease command-line manipulation of topology objects, binding of processes, and so on.

    -

    Bindings for several other languages are available from the project website.

    -

    -

    -

    -

    -hwloc Installation

    -

    The generic installation procedure for both hwloc and netloc is described in Installation.

    -

    The hwloc command-line tool "lstopo" produces human-readable topology maps, as mentioned above. It can also export maps to the "fig" file format. Support for PDF, Postscript, and PNG exporting is provided if the "Cairo" development package (usually cairo-devel or libcairo2-dev) can be found in "lstopo" when hwloc is configured and build.

    -

    The hwloc core may also benefit from the following development packages:

      -
    • -

      libpciaccess for full I/O device discovery (libpciaccess-devel or libpciaccess-dev package). On Linux, PCI discovery may still be performed (without vendor/device names) even if libpciaccess cannot be used.

      -

      -
      • -
    • -AMD or NVIDIA OpenCL implementations for OpenCL device discovery.
      • -
    • -the NVIDIA CUDA Toolkit for CUDA device discovery. See How do I enable CUDA and select which CUDA version to use?.
      • -
    • -the NVIDIA Management Library (NVML) for NVML device discovery. It is included in CUDA since version 8.0. Older NVML releases were available within the NVIDIA GPU Deployment Kit from https://developer.nvidia.com/gpu-deployment-kit .
      • -
    • -the NV-CONTROL X extension library (NVCtrl) for NVIDIA display discovery. The relevant development package is usually libXNVCtrl-devel or libxnvctrl-dev. It is also available within nvidia-settings from ftp://download.nvidia.com/XFree86/nvidia-settings/ and https://github.com/NVIDIA/nvidia-settings/ .
      • -
    • -the AMD ROCm SMI library for RSMI device discovery. The relevant development package is usually rocm-smi-lib64 or librocm-smi-dev. See How do I enable ROCm SMI and select which version to use?.
      • -
    • -the oneAPI Level Zero library. The relevant development package is usually level-zero-dev or level-zero-devel.
      • -
    • -libxml2 for full XML import/export support (otherwise, the internal minimalistic parser will only be able to import XML files that were exported by the same hwloc release). See Importing and exporting topologies from/to XML files for details. The relevant development package is usually libxml2-devel or libxml2-dev.
      • -
    • -libudev on Linux for easier discovery of OS device information (otherwise hwloc will try to manually parse udev raw files). The relevant development package is usually libudev-devel or libudev-dev.
      • -
    • -libtool's ltdl library for dynamic plugin loading if the native dlopen cannot be used. The relevant development package is usually libtool-ltdl-devel or libltdl-dev.
      • -
    -

    PCI and XML support may be statically built inside the main hwloc library, or as separate dynamically-loaded plugins (see the Components and plugins section).

    -

    Note that because of the possibility of GPL taint, the pciutils library libpci will not be used (remember that hwloc is BSD-licensed).

    -

    -

    -

    -

    -Command-line Examples

    -

    On a 4-package 2-core machine with hyper-threading, the lstopo tool may show the following graphical output:

    -
    - -
    -

    Here's the equivalent output in textual form:

    -
    Machine
-  NUMANode L#0 (P#0)
-  Package L#0 + L3 L#0 (4096KB)
-    L2 L#0 (1024KB) + L1 L#0 (16KB) + Core L#0
-      PU L#0 (P#0)
-      PU L#1 (P#8)
-    L2 L#1 (1024KB) + L1 L#1 (16KB) + Core L#1
-      PU L#2 (P#4)
-      PU L#3 (P#12)
-  Package L#1 + L3 L#1 (4096KB)
-    L2 L#2 (1024KB) + L1 L#2 (16KB) + Core L#2
-      PU L#4 (P#1)
-      PU L#5 (P#9)
-    L2 L#3 (1024KB) + L1 L#3 (16KB) + Core L#3
-      PU L#6 (P#5)
-      PU L#7 (P#13)
-  Package L#2 + L3 L#2 (4096KB)
-    L2 L#4 (1024KB) + L1 L#4 (16KB) + Core L#4
-      PU L#8 (P#2)
-      PU L#9 (P#10)
-    L2 L#5 (1024KB) + L1 L#5 (16KB) + Core L#5
-      PU L#10 (P#6)
-      PU L#11 (P#14)
-  Package L#3 + L3 L#3 (4096KB)
-    L2 L#6 (1024KB) + L1 L#6 (16KB) + Core L#6
-      PU L#12 (P#3)
-      PU L#13 (P#11)
-    L2 L#7 (1024KB) + L1 L#7 (16KB) + Core L#7
-      PU L#14 (P#7)
-      PU L#15 (P#15)
-

    Note that there is also an equivalent output in XML that is meant for exporting/importing topologies but it is hardly readable to human-beings (see Importing and exporting topologies from/to XML files for details).

    -

    On a 4-package 2-core Opteron NUMA machine (with two core cores disallowed by the administrator), the lstopo tool may show the following graphical output (with --disallowed for displaying disallowed objects):

    -
    - -
    -

    Here's the equivalent output in textual form:

    -
    Machine (32GB total)
-  Package L#0
-    NUMANode L#0 (P#0 8190MB)
-    L2 L#0 (1024KB) + L1 L#0 (64KB) + Core L#0 + PU L#0 (P#0)
-    L2 L#1 (1024KB) + L1 L#1 (64KB) + Core L#1 + PU L#1 (P#1)
-  Package L#1
-    NUMANode L#1 (P#1 8192MB)
-    L2 L#2 (1024KB) + L1 L#2 (64KB) + Core L#2 + PU L#2 (P#2)
-    L2 L#3 (1024KB) + L1 L#3 (64KB) + Core L#3 + PU L#3 (P#3)
-  Package L#2
-    NUMANode L#2 (P#2 8192MB)
-    L2 L#4 (1024KB) + L1 L#4 (64KB) + Core L#4 + PU L#4 (P#4)
-    L2 L#5 (1024KB) + L1 L#5 (64KB) + Core L#5 + PU L#5 (P#5)
-  Package L#3
-    NUMANode L#3 (P#3 8192MB)
-    L2 L#6 (1024KB) + L1 L#6 (64KB) + Core L#6 + PU L#6 (P#6)
-    L2 L#7 (1024KB) + L1 L#7 (64KB) + Core L#7 + PU L#7 (P#7)
-

    On a 2-package quad-core Xeon (pre-Nehalem, with 2 dual-core dies into each package):

    -
    - -
    -

    Here's the same output in textual form:

    -
    Machine (total 16GB)
-  NUMANode L#0 (P#0 16GB)
-  Package L#0
-    L2 L#0 (4096KB)
-      L1 L#0 (32KB) + Core L#0 + PU L#0 (P#0)
-      L1 L#1 (32KB) + Core L#1 + PU L#1 (P#4)
-    L2 L#1 (4096KB)
-      L1 L#2 (32KB) + Core L#2 + PU L#2 (P#2)
-      L1 L#3 (32KB) + Core L#3 + PU L#3 (P#6)
-  Package L#1
-    L2 L#2 (4096KB)
-      L1 L#4 (32KB) + Core L#4 + PU L#4 (P#1)
-      L1 L#5 (32KB) + Core L#5 + PU L#5 (P#5)
-    L2 L#3 (4096KB)
-      L1 L#6 (32KB) + Core L#6 + PU L#6 (P#3)
-      L1 L#7 (32KB) + Core L#7 + PU L#7 (P#7)
-

    -

    -

    -

    -Programming Interface

    -

    The basic interface is available in hwloc.h. Some higher-level functions are available in hwloc/helper.h to reduce the need to manually manipulate objects and follow links between them. Documentation for all these is provided later in this document. Developers may also want to look at hwloc/inlines.h which contains the actual inline code of some hwloc.h routines, and at this document, which provides good higher-level topology traversal examples.

    -

    To precisely define the vocabulary used by hwloc, a Terms and Definitions section is available and should probably be read first.

    -

    Each hwloc object contains a cpuset describing the list of processing units that it contains. These bitmaps may be used for CPU binding and Memory binding. hwloc offers an extensive bitmap manipulation interface in hwloc/bitmap.h.

    -

    Moreover, hwloc also comes with additional helpers for interoperability with several commonly used environments. See the Interoperability With Other Software section for details.

    -

    The complete API documentation is available in a full set of HTML pages, man pages, and self-contained PDF files (formatted for both both US letter and A4 formats) in the source tarball in doc/doxygen-doc/.

    -

    NOTE: If you are building the documentation from a Git clone, you will need to have Doxygen and pdflatex installed – the documentation will be built during the normal "make" process. The documentation is installed during "make install" to $prefix/share/doc/hwloc/ and your systems default man page tree (under $prefix, of course).

    -

    -Portability

    -

    Operating System have varying support for CPU and memory binding, e.g. while some Operating Systems provide interfaces for all kinds of CPU and memory bindings, some others provide only interfaces for a limited number of kinds of CPU and memory binding, and some do not provide any binding interface at all. Hwloc's binding functions would then simply return the ENOSYS error (Function not implemented), meaning that the underlying Operating System does not provide any interface for them. CPU binding and Memory binding provide more information on which hwloc binding functions should be preferred because interfaces for them are usually available on the supported Operating Systems.

    -

    Similarly, the ability of reporting topology information varies from one platform to another. As shown in Command-line Examples, hwloc can obtain information on a wide variety of hardware topologies. However, some platforms and/or operating system versions will only report a subset of this information. For example, on an PPC64-based system with 8 cores (each with 2 hardware threads) running a default 2.6.18-based kernel from RHEL 5.4, hwloc is only able to glean information about NUMA nodes and processor units (PUs). No information about caches, packages, or cores is available.

    -

    Here's the graphical output from lstopo on this platform when Simultaneous Multi-Threading (SMT) is enabled:

    -
    - -
    -

    And here's the graphical output from lstopo on this platform when SMT is disabled:

    -
    - -
    -

    Notice that hwloc only sees half the PUs when SMT is disabled. PU L#6, for example, seems to change location from NUMA node #0 to #1. In reality, no PUs "moved" – they were simply re-numbered when hwloc only saw half as many (see also Logical index in Indexes and Sets). Hence, PU L#6 in the SMT-disabled picture probably corresponds to PU L#12 in the SMT-enabled picture.

    -

    This same "PUs have disappeared" effect can be seen on other platforms – even platforms / OSs that provide much more information than the above PPC64 system. This is an unfortunate side-effect of how operating systems report information to hwloc.

    -

    Note that upgrading the Linux kernel on the same PPC64 system mentioned above to 2.6.34, hwloc is able to discover all the topology information. The following picture shows the entire topology layout when SMT is enabled:

    -
    - -
    -

    Developers using the hwloc API or XML output for portable applications should therefore be extremely careful to not make any assumptions about the structure of data that is returned. For example, per the above reported PPC topology, it is not safe to assume that PUs will always be descendants of cores.

    -

    Additionally, future hardware may insert new topology elements that are not available in this version of hwloc. Long-lived applications that are meant to span multiple different hardware platforms should also be careful about making structure assumptions. For example, a new element may someday exist between a core and a PU.

    -

    -API Example

    -

    The following small C example (available in the source tree as ``doc/examples/hwloc-hello.c'') prints the topology of the machine and performs some thread and memory binding. More examples are available in the doc/examples/ directory of the source tree.

    -
    /* Example hwloc API program.
    -
    *
    -
    * See other examples under doc/examples/ in the source tree
    -
    * for more details.
    -
    *
    -
    * Copyright © 2009-2016 Inria. All rights reserved.
    -
    * Copyright © 2009-2011 Université Bordeaux
    -
    * Copyright © 2009-2010 Cisco Systems, Inc. All rights reserved.
    -
    * See COPYING in top-level directory.
    -
    *
    -
    * hwloc-hello.c
    -
    */
    -
    -
    #include "hwloc.h"
    -
    -
    #include <errno.h>
    -
    #include <stdio.h>
    -
    #include <string.h>
    -
    -
    static void print_children(hwloc_topology_t topology, hwloc_obj_t obj,
    -
    int depth)
    -
    {
    -
    char type[32], attr[1024];
    -
    unsigned i;
    -
    -
    hwloc_obj_type_snprintf(type, sizeof(type), obj, 0);
    -
    printf("%*s%s", 2*depth, "", type);
    -
    if (obj->os_index != (unsigned) -1)
    -
    printf("#%u", obj->os_index);
    -
    hwloc_obj_attr_snprintf(attr, sizeof(attr), obj, " ", 0);
    -
    if (*attr)
    -
    printf("(%s)", attr);
    -
    printf("\n");
    -
    for (i = 0; i < obj->arity; i++) {
    -
    print_children(topology, obj->children[i], depth + 1);
    -
    }
    -
    }
    -
    -
    int main(void)
    -
    {
    -
    int depth;
    -
    unsigned i, n;
    -
    unsigned long size;
    -
    int levels;
    -
    char string[128];
    -
    int topodepth;
    -
    void *m;
    -
    hwloc_topology_t topology;
    -
    hwloc_cpuset_t cpuset;
    -
    hwloc_obj_t obj;
    -
    -
    /* Allocate and initialize topology object. */
    -
    hwloc_topology_init(&topology);
    -
    -
    /* ... Optionally, put detection configuration here to ignore
    -
    some objects types, define a synthetic topology, etc....
    -
    -
    The default is to detect all the objects of the machine that
    -
    the caller is allowed to access. See Configure Topology
    -
    Detection. */
    -
    -
    /* Perform the topology detection. */
    -
    hwloc_topology_load(topology);
    -
    -
    /* Optionally, get some additional topology information
    -
    in case we need the topology depth later. */
    -
    topodepth = hwloc_topology_get_depth(topology);
    -
    -
    /*****************************************************************
    -
    * First example:
    -
    * Walk the topology with an array style, from level 0 (always
    -
    * the system level) to the lowest level (always the proc level).
    -
    *****************************************************************/
    -
    for (depth = 0; depth < topodepth; depth++) {
    -
    printf("*** Objects at level %d\n", depth);
    -
    for (i = 0; i < hwloc_get_nbobjs_by_depth(topology, depth);
    -
    i++) {
    -
    hwloc_obj_type_snprintf(string, sizeof(string),
    -
    hwloc_get_obj_by_depth(topology, depth, i), 0);
    -
    printf("Index %u: %s\n", i, string);
    -
    }
    -
    }
    -
    -
    /*****************************************************************
    -
    * Second example:
    -
    * Walk the topology with a tree style.
    -
    *****************************************************************/
    -
    printf("*** Printing overall tree\n");
    -
    print_children(topology, hwloc_get_root_obj(topology), 0);
    -
    -
    /*****************************************************************
    -
    * Third example:
    -
    * Print the number of packages.
    -
    *****************************************************************/
    -
    depth = hwloc_get_type_depth(topology, HWLOC_OBJ_PACKAGE);
    -
    if (depth == HWLOC_TYPE_DEPTH_UNKNOWN) {
    -
    printf("*** The number of packages is unknown\n");
    -
    } else {
    -
    printf("*** %u package(s)\n",
    -
    hwloc_get_nbobjs_by_depth(topology, depth));
    -
    }
    -
    -
    /*****************************************************************
    -
    * Fourth example:
    -
    * Compute the amount of cache that the first logical processor
    -
    * has above it.
    -
    *****************************************************************/
    -
    levels = 0;
    -
    size = 0;
    -
    for (obj = hwloc_get_obj_by_type(topology, HWLOC_OBJ_PU, 0);
    -
    obj;
    -
    obj = obj->parent)
    -
    if (hwloc_obj_type_is_cache(obj->type)) {
    -
    levels++;
    -
    size += obj->attr->cache.size;
    -
    }
    -
    printf("*** Logical processor 0 has %d caches totaling %luKB\n",
    -
    levels, size / 1024);
    -
    -
    /*****************************************************************
    -
    * Fifth example:
    -
    * Bind to only one thread of the last core of the machine.
    -
    *
    -
    * First find out where cores are, or else smaller sets of CPUs if
    -
    * the OS doesn't have the notion of a "core".
    -
    *****************************************************************/
    -
    depth = hwloc_get_type_or_below_depth(topology, HWLOC_OBJ_CORE);
    -
    -
    /* Get last core. */
    -
    obj = hwloc_get_obj_by_depth(topology, depth,
    -
    hwloc_get_nbobjs_by_depth(topology, depth) - 1);
    -
    if (obj) {
    -
    /* Get a copy of its cpuset that we may modify. */
    -
    cpuset = hwloc_bitmap_dup(obj->cpuset);
    -
    -
    /* Get only one logical processor (in case the core is
    -
    SMT/hyper-threaded). */
    -
    hwloc_bitmap_singlify(cpuset);
    -
    -
    /* And try to bind ourself there. */
    -
    if (hwloc_set_cpubind(topology, cpuset, 0)) {
    -
    char *str;
    -
    int error = errno;
    -
    hwloc_bitmap_asprintf(&str, obj->cpuset);
    -
    printf("Couldn't bind to cpuset %s: %s\n", str, strerror(error));
    -
    free(str);
    -
    }
    -
    -
    /* Free our cpuset copy */
    -
    hwloc_bitmap_free(cpuset);
    -
    }
    -
    -
    /*****************************************************************
    -
    * Sixth example:
    -
    * Allocate some memory on the last NUMA node, bind some existing
    -
    * memory to the last NUMA node.
    -
    *****************************************************************/
    -
    /* Get last node. There's always at least one. */
    -
    n = hwloc_get_nbobjs_by_type(topology, HWLOC_OBJ_NUMANODE);
    -
    obj = hwloc_get_obj_by_type(topology, HWLOC_OBJ_NUMANODE, n - 1);
    -
    -
    size = 1024*1024;
    -
    m = hwloc_alloc_membind(topology, size, obj->nodeset,
    -
    HWLOC_MEMBIND_BIND, HWLOC_MEMBIND_BYNODESET);
    -
    hwloc_free(topology, m, size);
    -
    -
    m = malloc(size);
    -
    hwloc_set_area_membind(topology, m, size, obj->nodeset,
    -
    HWLOC_MEMBIND_BIND, HWLOC_MEMBIND_BYNODESET);
    -
    free(m);
    -
    -
    /* Destroy topology object. */
    -
    hwloc_topology_destroy(topology);
    -
    -
    return 0;
    -
    }
    -
    hwloc_cpuset_t
    hwloc_bitmap_t hwloc_cpuset_t
    A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
    Definition: hwloc.h:161
    -
    HWLOC_OBJ_NUMANODE
    @ HWLOC_OBJ_NUMANODE
    NUMA node. An object that contains memory that is directly and byte-accessible to the host processors...
    Definition: hwloc.h:257
    -
    HWLOC_OBJ_PACKAGE
    @ HWLOC_OBJ_PACKAGE
    Physical package. The physical package that usually gets inserted into a socket on the motherboard....
    Definition: hwloc.h:212
    -
    HWLOC_OBJ_PU
    @ HWLOC_OBJ_PU
    Processing Unit, or (Logical) Processor. An execution unit (may share a core with some other logical ...
    Definition: hwloc.h:222
    -
    HWLOC_OBJ_CORE
    @ HWLOC_OBJ_CORE
    Core. A computation unit (may be shared by several PUs, aka logical processors).
    Definition: hwloc.h:218
    -
    hwloc_topology_init
    int hwloc_topology_init(hwloc_topology_t *topologyp)
    Allocate a topology context.
    -
    hwloc_topology_t
    struct hwloc_topology * hwloc_topology_t
    Topology context.
    Definition: hwloc.h:716
    -
    hwloc_topology_destroy
    void hwloc_topology_destroy(hwloc_topology_t topology)
    Terminate and free a topology context.
    -
    hwloc_topology_load
    int hwloc_topology_load(hwloc_topology_t topology)
    Build the actual topology.
    -
    hwloc_get_nbobjs_by_depth
    unsigned hwloc_get_nbobjs_by_depth(hwloc_topology_t topology, int depth)
    Returns the width of level at depth depth.
    -
    hwloc_get_root_obj
    static hwloc_obj_t hwloc_get_root_obj(hwloc_topology_t topology)
    Returns the top-object of the topology-tree.
    -
    hwloc_get_obj_by_depth
    hwloc_obj_t hwloc_get_obj_by_depth(hwloc_topology_t topology, int depth, unsigned idx)
    Returns the topology object at logical index idx from depth depth.
    -
    hwloc_get_obj_by_type
    static hwloc_obj_t hwloc_get_obj_by_type(hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx)
    Returns the topology object at logical index idx with type type.
    -
    hwloc_get_nbobjs_by_type
    static int hwloc_get_nbobjs_by_type(hwloc_topology_t topology, hwloc_obj_type_t type)
    Returns the width of level type type.
    -
    hwloc_get_type_or_below_depth
    static int hwloc_get_type_or_below_depth(hwloc_topology_t topology, hwloc_obj_type_t type)
    Returns the depth of objects of type type or below.
    -
    hwloc_get_type_depth
    int hwloc_get_type_depth(hwloc_topology_t topology, hwloc_obj_type_t type)
    Returns the depth of objects of type type.
    -
    hwloc_topology_get_depth
    int hwloc_topology_get_depth(hwloc_topology_t restrict topology)
    Get the depth of the hierarchical tree of objects.
    -
    HWLOC_TYPE_DEPTH_UNKNOWN
    @ HWLOC_TYPE_DEPTH_UNKNOWN
    No object of given type exists in the topology.
    Definition: hwloc.h:853
    -
    hwloc_obj_attr_snprintf
    int hwloc_obj_attr_snprintf(char *restrict string, size_t size, hwloc_obj_t obj, const char *restrict separator, int verbose)
    Stringify the attributes of a given topology object into a human-readable form.
    -
    hwloc_obj_type_snprintf
    int hwloc_obj_type_snprintf(char *restrict string, size_t size, hwloc_obj_t obj, int verbose)
    Stringify the type of a given topology object into a human-readable form.
    -
    hwloc_set_cpubind
    int hwloc_set_cpubind(hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags)
    Bind current process or thread on CPUs given in physical bitmap set.
    -
    hwloc_free
    int hwloc_free(hwloc_topology_t topology, void *addr, size_t len)
    Free memory that was previously allocated by hwloc_alloc() or hwloc_alloc_membind().
    -
    hwloc_alloc_membind
    void * hwloc_alloc_membind(hwloc_topology_t topology, size_t len, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags)
    Allocate some memory on NUMA memory nodes specified by set.
    -
    hwloc_set_area_membind
    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)
    Bind the already-allocated memory identified by (addr, len) to the NUMA node(s) specified by set.
    -
    HWLOC_MEMBIND_BYNODESET
    @ HWLOC_MEMBIND_BYNODESET
    Consider the bitmap argument as a nodeset.
    Definition: hwloc.h:1576
    -
    HWLOC_MEMBIND_BIND
    @ HWLOC_MEMBIND_BIND
    Allocate memory on the specified nodes.
    Definition: hwloc.h:1488
    -
    hwloc_obj_type_is_cache
    int hwloc_obj_type_is_cache(hwloc_obj_type_t type)
    Check whether an object type is a CPU Cache (Data, Unified or Instruction).
    -
    hwloc_bitmap_asprintf
    int hwloc_bitmap_asprintf(char **strp, hwloc_const_bitmap_t bitmap)
    Stringify a bitmap into a newly allocated string.
    -
    hwloc_bitmap_free
    void hwloc_bitmap_free(hwloc_bitmap_t bitmap)
    Free bitmap bitmap.
    -
    hwloc_bitmap_singlify
    int hwloc_bitmap_singlify(hwloc_bitmap_t bitmap)
    Keep a single index among those set in bitmap bitmap.
    -
    hwloc_bitmap_dup
    hwloc_bitmap_t hwloc_bitmap_dup(hwloc_const_bitmap_t bitmap)
    Duplicate bitmap bitmap by allocating a new bitmap and copying bitmap contents.
    -
    hwloc_obj
    Structure of a topology object.
    Definition: hwloc.h:420
    -
    hwloc_obj::children
    struct hwloc_obj ** children
    Normal children, children[0 .. arity -1].
    Definition: hwloc.h:480
    -
    hwloc_obj::nodeset
    hwloc_nodeset_t nodeset
    NUMA nodes covered by this object or containing this object.
    Definition: hwloc.h:564
    -
    hwloc_obj::os_index
    unsigned os_index
    OS-provided physical index number. It is not guaranteed unique across the entire machine,...
    Definition: hwloc.h:425
    -
    hwloc_obj::cpuset
    hwloc_cpuset_t cpuset
    CPUs covered by this object.
    Definition: hwloc.h:536
    -
    hwloc_obj::arity
    unsigned arity
    Number of normal children. Memory, Misc and I/O children are not listed here but rather in their dedi...
    Definition: hwloc.h:476
    -
    hwloc_obj::type
    hwloc_obj_type_t type
    Type of object.
    Definition: hwloc.h:422
    -
    hwloc_obj::attr
    union hwloc_obj_attr_u * attr
    Object type-specific Attributes, may be NULL if no attribute value was found.
    Definition: hwloc.h:439
    -
    hwloc_obj::parent
    struct hwloc_obj * parent
    Parent, NULL if root (Machine object)
    Definition: hwloc.h:470
    -
    hwloc_obj_attr_u::cache
    struct hwloc_obj_attr_u::hwloc_cache_attr_s cache
    -
    hwloc_obj_attr_u::hwloc_cache_attr_s::size
    hwloc_uint64_t size
    Size of cache in bytes.
    Definition: hwloc.h:641
    -

    hwloc provides a pkg-config executable to obtain relevant compiler and linker flags. For example, it can be used thusly to compile applications that utilize the hwloc library (assuming GNU Make):

    -
    CFLAGS += $(shell pkg-config --cflags hwloc)
-LDLIBS += $(shell pkg-config --libs hwloc)
-
-hwloc-hello: hwloc-hello.c
-        $(CC) hwloc-hello.c $(CFLAGS) -o hwloc-hello $(LDLIBS)
-

    On a machine 2 processor packages – each package of which has two processing cores – the output from running hwloc-hello could be something like the following:

    -
    shell$ ./hwloc-hello
-*** Objects at level 0
-Index 0: Machine
-*** Objects at level 1
-Index 0: Package#0
-Index 1: Package#1
-*** Objects at level 2
-Index 0: Core#0
-Index 1: Core#1
-Index 2: Core#3
-Index 3: Core#2
-*** Objects at level 3
-Index 0: PU#0
-Index 1: PU#1
-Index 2: PU#2
-Index 3: PU#3
-*** Printing overall tree
-Machine
-  Package#0
-    Core#0
-      PU#0
-    Core#1
-      PU#1
-  Package#1
-    Core#3
-      PU#2
-    Core#2
-      PU#3
-*** 2 package(s)
-*** Logical processor 0 has 0 caches totaling 0KB
-shell$ 
-

    -

    -

    -

    -History / Credits

    -

    hwloc is the evolution and merger of the libtopology project and the Portable Linux Processor Affinity (PLPA) (https://www.open-mpi.org/projects/plpa/) project. Because of functional and ideological overlap, these two code bases and ideas were merged and released under the name "hwloc" as an Open MPI sub-project.

    -

    libtopology was initially developed by the Inria Runtime Team-Project. PLPA was initially developed by the Open MPI development team as a sub-project. Both are now deprecated in favor of hwloc, which is distributed as an Open MPI sub-project.

    -

    -

    -

    -
    -
    - - - - - - - -
    -
    Terms and Definitions
    -
    -
    -

    -

    -

    -

    -Objects

    -
    -
    Object
    -

    Interesting kind of part of the system, such as a Core, a L2Cache, a NUMA memory node, etc. The different types detected by hwloc are detailed in the hwloc_obj_type_t enumeration.

    -

    There are four kinds of Objects: Memory (NUMA nodes and Memory-side caches), I/O (Bridges, PCI and OS devices), Misc, and Normal (everything else, including Machine, Package, Die, Core, PU, CPU Caches, etc.). Normal and Memory objects have (non-NULL) CPU sets and nodesets, while I/O and Misc don't.

    -

    Objects are topologically sorted by locality (CPU and node sets) into a tree (see Hierarchy, Tree and Levels).

    -

    -
    -
    Processing Unit (PU)
    -

    The smallest processing element that can be represented by a hwloc object. It may be a single-core processor, a core of a multicore processor, or a single thread in a SMT processor (also sometimes called "Logical processor", not to be confused with "Logical index of a processor"). hwloc's PU acronym stands for Processing Unit.

    -

    -
    -
    Package
    -

    A processor Package is the physical package that usually gets inserted into a socket on the motherboard. It is also often called a physical processor or a CPU even if these names bring confusion with respect to cores and processing units. A processor package usually contains multiple cores (and may also be composed of multiple dies). hwloc Package objects were called Sockets up to hwloc 1.10.

    -

    -
    -
    NUMA Node
    -

    An object that contains memory that is directly and byte-accessible to the host processors. It is usually close to some cores as specified by its CPU set. Hence it is attached as a memory child of the object that groups those cores together, for instance a Package objects with 4 Core children (see Hierarchy, Tree and Levels).

    -

    -
    -
    Memory-side Cache
    -

    A cache in front of a specific memory region (e.g. a range of physical addresses). It caches all accesses to that region without caring about which core issued the request. This is the opposite of usual CPU caches where only accesses from the local cores are cached, without caring about the target memory.

    -

    In hwloc, memory-side caches are memory objects placed between their local CPU objects (parent) and the target NUMA node memory (child).

    -
    -
    -

    -

    -

    -

    -Indexes and Sets

    -
    -
    OS or physical index
    -

    The index that the operating system (OS) uses to identify the object. This may be completely arbitrary, non-unique, non-contiguous, not representative of logical proximity, and may depend on the BIOS configuration. That is why hwloc almost never uses them, only in the default lstopo output (P#x) and cpuset masks. See also Should I use logical or physical/OS indexes? and how?.

    -

    -
    -
    Logical index
    -

    Index to uniquely identify objects of the same type and depth, automatically computed by hwloc according to the topology. It expresses logical proximity in a generic way, i.e. objects which have adjacent logical indexes are adjacent in the topology. That is why hwloc almost always uses it in its API, since it expresses logical proximity. They can be shown (as L#x) by lstopo thanks to the -l option. This index is always linear and in the range [0, num_objs_same_type_same_level-1]. Think of it as ``cousin rank.'' The ordering is based on topology first, and then on OS CPU numbers, so it is stable across everything except firmware CPU renumbering. "Logical index" should not be confused with "Logical processor". A "Logical - processor" (which in hwloc we rather call "processing unit" to avoid the confusion) has both a physical index (as chosen arbitrarily by BIOS/OS) and a logical index (as computed according to logical proximity by hwloc). See also Should I use logical or physical/OS indexes? and how?.

    -

    -
    -
    CPU set
    -

    The set of processing units (PU) logically included in an object (if it makes sense). They are always expressed using physical processor numbers (as announced by the OS). They are implemented as the hwloc_bitmap_t opaque structure. hwloc CPU sets are just masks, they do not have any relation with an operating system actual binding notion like Linux' cpusets. I/O and Misc objects do not have CPU sets while all Normal and Memory objects have non-NULL CPU sets.

    -

    -
    -
    Node set
    -

    The set of NUMA memory nodes logically included in an object (if it makes sense). They are always expressed using physical node numbers (as announced by the OS). They are implemented with the hwloc_bitmap_t opaque structure. as bitmaps. I/O and Misc objects do not have Node sets while all Normal and Memory objects have non-NULL nodesets.

    -

    -
    -
    Bitmap
    -

    A possibly-infinite set of bits used for describing sets of objects such as CPUs (CPU sets) or memory nodes (Node sets). They are implemented with the hwloc_bitmap_t opaque structure.

    -

    -
    -
    -

    -

    -

    -

    -Hierarchy, Tree and Levels

    -
    -
    Parent object
    -

    The object logically containing the current object, for example because its CPU set includes the CPU set of the current object. All objects have a non-NULL parent, except the root of the topology (Machine object).

    -

    -
    -
    Ancestor object
    -

    The parent object, or its own parent, and so on.

    -

    -
    -
    Children object(s)
    -

    The object (or objects) contained in the current object because their CPU set is included in the CPU set of the current object. Each object may also contain separated lists for Memory, I/O and Misc object children.

    -

    -
    -
    Arity
    -

    The number of normal children of an object. There are also specific arities for Memory, I/O and Misc children.

    -

    -
    -
    Sibling objects
    -

    Objects in the same children list, which all of them are normal children of the same parent, or all of them are Memory children of the same parent, or I/O children, or Misc. They usually have the same type (and hence are cousins, as well). But they may not if the topology is asymmetric.

    -

    -
    -
    Sibling rank
    -

    Index to uniquely identify objects which have the same parent, and is always in the range [0, arity-1] (respectively memory_arity, io_arity or misc_arity for Memory, I/O and Misc children of a parent).

    -

    -
    -
    Cousin objects
    -

    Objects of the same type (and depth) as the current object, even if they do not have the same parent.

    -

    -
    -
    Level
    -

    Set of objects of the same type and depth. All these objects are cousins.

    -

    Memory, I/O and Misc objects also have their own specific levels and (virtual) depth.

    -

    -
    -
    Depth
    -

    Nesting level in the object tree, starting from the root object. If the topology is symmetric, the depth of a child is equal to the parent depth plus one, and an object depth is also equal to the number of parent/child links between the root object and the given object. If the topology is asymmetric, the difference between some parent and child depths may be larger than one when some intermediate levels (for instance groups) are missing in only some parts of the machine.

    -

    The depth of the Machine object is always 0 since it is always the root of the topology. The depth of PU objects is equal to the number of levels in the topology minus one.

    -

    Memory, I/O and Misc objects also have their own specific levels and depth.

    -

    -
    -
    -

    The following diagram can help to understand the vocabulary of the relationships by showing the example of a machine with two dual core packages (with no hardware threads); thus, a topology with 5 levels. Each box with rounded corner corresponds to one hwloc_obj_t, containing the values of the different integer fields (depth, logical_index, etc.), and arrows show to which other hwloc_obj_t pointers point to (first_child, parent, etc.).

    -

    The topology always starts with a Machine object as root (depth 0) and ends with PU objects at the bottom (depth 4 here).

    -

    Objects of the same level (cousins) are listed in red boxes and linked with red arrows. Children of the same parent (siblings) are linked with blue arrows.

    -

    The L2 cache of the last core is intentionally missing to show how asymmetric topologies are handled. See What happens if my topology is asymmetric? for more information about such strange topologies.

    -
    - -
    -

    It should be noted that for PU objects, the logical index – as computed linearly by hwloc – is not the same as the OS index.

    -

    The NUMA node is on the side because it is not part of the main tree but rather attached to the object that corresponds to its locality (the entire machine here, hence the root object). It is attached as a Memory child (in green) and has a virtual depth (negative). It could also have siblings if there were multiple local NUMA nodes, or cousins if other NUMA nodes were attached somewhere else in the machine.

    -

    I/O or Misc objects could be attached in a similar manner.

    -
    -
    - - - - - - -
    -
    -
    Command-Line Tools
    -
    -
    -

    -

    -

    -

    hwloc comes with an extensive C programming interface and several command line utilities. Each of them is fully documented in its own manual page; the following is a summary of the available command line tools.

    -

    -

    -

    -

    -lstopo and lstopo-no-graphics

    -

    lstopo (also known as hwloc-ls) displays the hierarchical topology map of the current system. The output may be graphical, ascii-art or textual, and can also be exported to numerous file formats such as PDF, PNG, XML, and others. Advanced graphical outputs require the "Cairo" development package (usually cairo-devel or libcairo2-dev).

    -

    lstopo and lstopo-no-graphics accept the same command-line options. However, graphical outputs are only available in lstopo. Textual outputs (those that do not depend on heavy external libraries such as Cairo) are supported in both lstopo and lstopo-no-graphics.

    -

    This command can also display the processes currently bound to a part of the machine (via the --ps option).

    -

    Note that lstopo can read XML files and/or alternate chroot filesystems and display topological maps representing those systems (e.g., use lstopo to output an XML file on one system, and then use lstopo to read in that XML file and display it on a different system).

    -

    -

    -

    -

    -hwloc-bind

    -

    hwloc-bind binds processes to specific hardware objects through a flexible syntax. A simple example is binding an executable to specific cores (or packages or bitmaps or ...). The hwloc-bind(1) man page provides much more detail on what is possible.

    -

    hwloc-bind can also be used to retrieve the current process' binding, or retrieve the last CPU(s) where a process ran, or operate on memory binding.

    -

    Just like hwloc-calc, the input locations given to hwloc-bind may be either objects or cpusets (bitmaps as reported by hwloc-calc or hwloc-distrib).

    -

    -

    -

    -

    -hwloc-calc

    -

    hwloc-calc is hwloc's Swiss Army Knife command-line tool for converting things. The input may be either objects or cpusets (bitmaps as reported by another hwloc-calc instance or by hwloc-distrib), that may be combined by addition, intersection or subtraction. The output may be expressed as:

      -
    • -a cpuset bitmap: This compact opaque representation of objects is useful for shell scripts etc. It may passed to hwloc command-line tools such as hwloc-calc or hwloc-bind, or to hwloc command-line options such as lstopo --restrict.
      • -
    • -a nodeset bitmap: Another opaque representation that represents memory locality more precisely, especially if some NUMA nodes are CPU less or if multiple NUMA nodes are local to the same CPUs.
      • -
    • -the amount of the equivalent hwloc objects from a specific type, or the list of their indexes. This is useful for iterating over all similar objects (for instance all cores) within a given part of a platform.
      • -
    • -a hierarchical description of objects, for instance a thread index within a core within a package. This gives a better view of the actual location of an object.
      • -
    -

    Moreover, input and/or output may be use either physical/OS object indexes or as hwloc's logical object indexes. It eases cooperation with external tools such as taskset or numactl by exporting hwloc specifications into list of processor or NUMA node physical indexes. See also Should I use logical or physical/OS indexes? and how?.

    -

    -

    -

    -

    -hwloc-info

    -

    hwloc-info dumps information about the given objects, as well as all its specific attributes. It is intended to be used with tools such as grep for filtering certain attribute lines. When no object is specified, or when --topology is passed, hwloc-info prints a summary of the topology. When --support is passed, hwloc-info lists the supported features for the topology.

    -

    -

    -

    -

    -hwloc-distrib

    -

    hwloc-distrib generates a set of cpuset bitmaps that are uniformly distributed across the machine for the given number of processes. These strings may be used with hwloc-bind to run processes to maximize their memory bandwidth by properly distributing them across the machine.

    -

    -

    -

    -

    -hwloc-ps

    -

    hwloc-ps is a tool to display the bindings of processes that are currently running on the local machine. By default, hwloc-ps only lists processes that are bound; unbound process (and Linux kernel threads) are not displayed.

    -

    -

    -

    -

    -hwloc-annotate

    -

    hwloc-annotate may modify object (and topology) attributes such as string information (see Custom string infos for details) or Misc children objects. It may also add distances, memory attributes, etc. to the topology. It reads an input topology from a XML file and outputs the annotated topology as another XML file.

    -

    -

    -

    -

    -hwloc-diff, hwloc-patch and hwloc-compress-dir

    -

    hwloc-diff computes the difference between two topologies and outputs it to another XML file.

    -

    hwloc-patch reads such a difference file and applies to another topology.

    -

    hwloc-compress-dir compresses an entire directory of XML files by using hwloc-diff to save the differences between topologies instead of entire topologies.

    -

    -

    -

    -

    -hwloc-dump-hwdata

    -

    hwloc-dump-hwdata is a Linux and x86-specific tool that dumps (during boot, privileged) some topology and locality information from raw hardware files (SMBIOS and ACPI tables) to human-readable and world-accessible files that the hwloc library will later reuse.

    -

    Currently only used on Intel Xeon Phi processor platforms. See Why do I need hwloc-dump-hwdata for memory on Intel Xeon Phi processor?.

    -

    See HWLOC_DUMPED_HWDATA_DIR in Environment Variables for details about the location of dumped files.

    -

    -

    -

    -

    -hwloc-gather-topology and hwloc-gather-cpuid

    -

    hwloc-gather-topology is a Linux-specific tool that saves the relevant topology files of the current machine into a tarball (and the corresponding lstopo outputs).

    -

    hwloc-gather-cpuid is a x86-specific tool that dumps the result of CPUID instructions on the current machine into a directory.

    -

    The output of hwloc-gather-cpuid is included in the tarball saved by hwloc-gather-topology when running on Linux/x86.

    -

    These files may be used later (possibly offline) for simulating or debugging a machine without actually running on it.

    -
    -
    - - - - - - -
    -
    -
    Environment Variables
    -
    -
    -

    -

    -

    -

    The behavior of the hwloc library and tools may be tuned thanks to the following environment variables.

    -
    -
    HWLOC_XMLFILE=/path/to/file.xml
    -

    enforces the discovery from the given XML file as if hwloc_topology_set_xml() had been called. This file may have been generated earlier with lstopo file.xml. For convenience, this backend provides empty binding hooks which just return success. To have hwloc still actually call OS-specific hooks, HWLOC_THISSYSTEM should be set 1 in the environment too, to assert that the loaded file is really the underlying system. See also Importing and exporting topologies from/to XML files.

    -

    -
    -
    HWLOC_SYNTHETIC=synthetic_description
    -

    enforces the discovery through a synthetic description string as if hwloc_topology_set_synthetic() had been called. For convenience, this backend provides empty binding hooks which just return success. See also Synthetic topologies.

    -

    -
    -
    HWLOC_XML_VERBOSE=1
    -
    -
    HWLOC_SYNTHETIC_VERBOSE=1
    -

    enables verbose messages in the XML or synthetic topology backends. hwloc XML backends (see Importing and exporting topologies from/to XML files) can emit some error messages to the error output stream. Enabling these verbose messages within hwloc can be useful for understanding failures to parse input XML topologies. Similarly, enabling verbose messages in the synthetic topology backend can help understand why the description string is invalid. See also Synthetic topologies.

    -

    -
    -
    HWLOC_THISSYSTEM=1
    -

    enforces the return value of hwloc_topology_is_thissystem(), as if HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM was set with hwloc_topology_set_flags(). It means that it makes hwloc assume that the selected backend provides the topology for the system on which we are running, even if it is not the OS-specific backend but the XML backend for instance. This means making the binding functions actually call the OS-specific system calls and really do binding, while the XML backend would otherwise provide empty hooks just returning success. This can be used for efficiency reasons to first detect the topology once, save it to a XML file, and quickly reload it later through the XML backend, but still having binding functions actually do bind. This also enables support for the variable HWLOC_THISSYSTEM_ALLOWED_RESOURCES.

    -

    -
    -
    HWLOC_THISSYSTEM_ALLOWED_RESOURCES=1
    -

    Get the set of allowed resources from the native operating system even if the topology was loaded from XML or synthetic description, as if HWLOC_TOPOLOGY_FLAG_THISSYSTEM_ALLOWED_RESOURCES was set with hwloc_topology_set_flags(). This variable requires the topology to match the current system (see the variable HWLOC_THISSYSTEM). This is useful when the topology is not loaded directly from the local machine (e.g. for performance reason) and it comes with all resources, but the running process is restricted to only a part of the machine (for instance because of Linux Cgroup/Cpuset).

    -

    -
    -
    HWLOC_ALLOW=all
    -

    Totally ignore administrative restrictions such as Linux Cgroups and consider all resources (PUs and NUMA nodes) as allowed. This is different from setting HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED which gathers all resources but marks the unavailable ones as disallowed.

    -

    -
    -
    HWLOC_HIDE_ERRORS=1
    -

    enables or disables verbose reporting of errors. The hwloc library may issue warnings to the standard error stream when it detects a problem during topology discovery, for instance if the operating system (or user) gives contradictory topology information.

    -

    By default (1), hwloc only shows critical errors such as invalid hardware topology information or invalid configuration. If set to 0 (default in lstopo), more errors are displayed, for instance a failure to initialize CUDA or NVML. If set to 2, no hwloc error messages are shown.

    -

    Note that additional verbose messages may be enabled with other variables such as HWLOC_GROUPING_VERBOSE.

    -

    -
    -
    HWLOC_USE_NUMA_DISTANCES=7
    -

    enables or disables the use of NUMA distances. NUMA distances and memory target/initiator information may be used to improve the locality of NUMA nodes, especially CPU-less nodes. Bits in the value of this environment variable enable different features: Bit 0 enables the gathering of NUMA distances from the operating system. Bit 1 further enables the use of NUMA distances to improve the locality of CPU-less nodes. Bit 2 enables the use of target/initiator information.

    -

    -
    -
    HWLOC_GROUPING=1
    -

    enables or disables objects grouping based on distances. By default, hwloc uses distance matrices between objects (either read from the OS or given by the user) to find groups of close objects. These groups are described by adding intermediate Group objects in the topology. Setting this environment variable to 0 will disable this grouping. This variable supersedes the obsolete HWLOC_IGNORE_DISTANCES variable.

    -

    -
    -
    HWLOC_GROUPING_ACCURACY=0.05
    -

    relaxes distance comparison during grouping. By default, objects may be grouped if their distances form a minimal distance graph. When setting this variable to 0.02, and when HWLOC_DISTANCES_ADD_FLAG_GROUP_INACCURATE is given, these distances do not have to be strictly equal anymore, they may just be equal with a 2% error. If set to try instead of a numerical value, hwloc will try to group with perfect accuracy (0, the default), then with 0.01, 0.02, 0.05 and finally 0.1. Numbers given in this environment variable should always use a dot as a decimal mark (for instance 0.01 instead of 0,01).

    -

    -
    -
    HWLOC_GROUPING_VERBOSE=0
    -

    enables or disables some verbose messages during grouping. If this variable is set to 1, some debug messages will be displayed during distance-based grouping of objects even if debug was not specific at configure time. This is useful when trying to find an interesting distance grouping accuracy.

    -

    -
    -
    HWLOC_CPUKINDS_RANKING=default
    -

    change the ranking policy for CPU kinds. hwloc tries to rank CPU kinds that are energy efficiency first, and then CPUs that are rather high-performance and power hungry.
    - By default, if available, the OS-provided efficiency is used for ranking. Otherwise, the frequency and/or core types are used when available.
    - This environment variable may be set to coretype+frequency, coretype+frequency_strict, coretype, frequency, frequency_base, frequency_max, forced_efficiency, no_forced_efficiency, default, or none.

    -

    -
    -
    HWLOC_CPUKINDS_MAXFREQ=adjust=10
    -

    change the use of the max frequency in the Linux backend. hwloc tries to read the base and max frequencies of each core on Linux. Some hardware features such as Intel Turbo Boost Max 3.0 make some cores report slightly higher max frequencies than others in the same CPU package. Despite having slightly different frequencies, these cores are considered identical instead of exposing an hybrid CPU. Hence, by default, hwloc uniformizes the max frequencies of cores that have the same base frequency (higher values are downgraded by up to 10%).

    -

    If this environment variable is set to adjust=X, the 10% threshold is replaced with X. If set to 1, max frequencies are not adjusted anymore, some homogeneous processors may appear hybrid because of this. If set to 0, max frequencies are entirely ignored.

    -

    -
    -
    HWLOC_PCI_LOCALITY=<domain/bus> <cpuset>;...
    -
    -
    HWLOC_PCI_LOCALITY=/path/to/pci/locality/file
    -

    changes the locality of I/O devices behing the specified PCI buses. If no I/O locality information is available or if the BIOS reports incorrect information, it is possible to move a I/O device tree (OS and/or PCI devices with optional bridges) near a custom set of processors.
    - Localities are given either inside the environment variable itself, or in the pointed file. They may be separated either by semi-colons or by line-breaks. Invalid localities are silently ignored, hence it is possible to insert comments between actual localities.
    - Each locality contains a domain/bus specification (in hexadecimal numbers as usual) followed by a whitespace and a cpuset:

      -
    • -0001 <cpuset> specifies the locality of all buses in PCI domain 0000.
      • -
    • -0000:0f <cpuset> specifies only PCI bus 0f in domain 0000.
      • -
    • -0002:04-0a <cpuset> specifies a range of buses (from 04 to 0a) within domain 0002.
      • -
    -

    Domain/bus specifications should usually match entire hierarchies of buses behind a bridge (including primary, secondary and subordinate buses). For instance, if hostbridge 0000:00 is above other bridges/switches with buses 0000:01 to 0000:09, the variable should be HWLOC_PCI_LOCALITY="0000:00-09 <cpuset>". It supersedes the old HWLOC_PCI_0000_00_LOCALCPUS=<cpuset> which only works when hostbridges exist in the topology.
    - If the variable is defined to empty or invalid, no forced PCI locality is applied but hwloc's internal automatic locality quirks are disabled, which means the exact PCI locality reported by the platform is used.

    -

    -
    -
    HWLOC_X86_TOPOEXT_NUMANODES=0
    -

    use AMD topoext CPUID leaf in the x86 backend to detect NUMA nodes. When using the x86 backend, setting this variable to 1 enables the building of NUMA nodes from AMD processor CPUID instructions. However this strategy does not always reflect BIOS configuration such as NUMA interleaving. And node indexes may be different from those of the operating system. Hence this should only be used when OS backends are wrong and the user is sure that CPUID returns correct NUMA information.

    -

    -
    -
    HWLOC_KEEP_NVIDIA_GPU_NUMA_NODES=0
    -

    show or hide NUMA nodes that correspond to NVIDIA GPU memory. By default they are ignored to avoid interleaved memory being allocated on GPU by mistake. Setting this environment variable to 1 exposes these NUMA nodes. They may be recognized by the GPUMemory subtype. They also have a PCIBusID info attribute to identify the corresponding GPU.

    -

    -
    -
    HWLOC_KNL_MSCACHE_L3=0
    -

    Expose the KNL MCDRAM in cache mode as a Memory-side Cache instead of a L3. hwloc releases prior to 2.1 exposed the MCDRAM cache as a CPU-side L3 cache. Now that Memory-side caches are supported by hwloc, it is still exposed as a L3 by default to avoid breaking existing applications. Setting this environment variable to 1 will expose it as a proper Memory-side cache.

    -

    -
    -
    HWLOC_WINDOWS_PROCESSOR_GROUP_OBJS=0
    -

    Expose Windows processor groups as hwloc Group objects. By default, these groups are disabled because they may be incompatible with the hierarchy of resources that hwloc builds (leading to warnings). Setting this variable to 1 reenables the addition of these groups to the topology.

    -

    This variable does not impact the querying of Windows processor groups using the dedicated API in hwloc/windows.h, this feature is always supported.

    -

    -
    -
    HWLOC_ANNOTATE_GLOBAL_COMPONENTS=0
    -

    Allow components to annotate the topology even if they are usually excluded by global components by default. Setting this variable to 1 and also setting HWLOC_COMPONENTS=xml,pci,stop enables the addition of PCI vendor and model info attributes to a XML topology that was generated without those names (if pciaccess was missing).

    -

    -
    -
    HWLOC_FSROOT=/path/to/linux/filesystem-root/
    -

    switches to reading the topology from the specified Linux filesystem root instead of the main file-system root. This directory may have been saved previously from another machine with hwloc-gather-topology.
    - One should likely also set HWLOC_COMPONENTS=linux,stop so that non-Linux backends are disabled (the -i option of command-line tools takes care of both).
    - Not using the main file-system root causes hwloc_topology_is_thissystem() to return 0. For convenience, this backend provides empty binding hooks which just return success. To have hwloc still actually call OS-specific hooks, HWLOC_THISSYSTEM should be set 1 in the environment too, to assert that the loaded file is really the underlying system.

    -

    -
    -
    HWLOC_CPUID_PATH=/path/to/cpuid/
    -

    forces the x86 backend to read dumped CPUIDs from the given directory instead of executing actual x86 CPUID instructions. This directory may have been saved previously from another machine with hwloc-gather-cpuid.
    - One should likely also set HWLOC_COMPONENTS=x86,stop so that non-x86 backends are disabled (the -i option of command-line tools takes care of both).
    - It causes hwloc_topology_is_thissystem() to return 0. For convenience, this backend provides empty binding hooks which just return success. To have hwloc still actually call OS-specific hooks, HWLOC_THISSYSTEM should be set 1 in the environment too, to assert that the loaded CPUID dump is really the underlying system.

    -

    -
    -
    HWLOC_DUMPED_HWDATA_DIR=/path/to/dumped/files/
    -

    loads files dumped by hwloc-dump-hwdata (on Linux) from the given directory. The default dump/load directory is configured during build based on --runstatedir, --localstatedir, and --prefix options. It usually points to /var/run/hwloc/ in Linux distribution packages, but it may also point to $prefix/var/run/hwloc/ when manually installing and only specifying --prefix.

    -

    -
    -
    HWLOC_COMPONENTS=list,of,components
    -

    forces a list of components to enable or disable. Enable or disable the given comma-separated list of components (if they do not conflict with each other). Component names prefixed with - are disabled (a single phase may also be disabled).

    -

    Once the end of the list is reached, hwloc falls back to enabling the remaining components (sorted by priority) that do not conflict with the already enabled ones, and unless explicitly disabled in the list. If stop is met, the enabling loop immediately stops, no more component is enabled.

    -

    If xml or synthetic components are selected, the corresponding XML filename or synthetic description string should be pass in HWLOC_XMLFILE or HWLOC_SYNTHETIC respectively.

    -

    Since this variable is the low-level and more generic way to select components, it takes precedence over environment variables for selecting components.

    -

    If the variable is set to an empty string (or set to a single comma), no specific component is loaded first, all components are loaded in priority order.

    -

    See Selecting which components to use for details.

    -

    -
    -
    HWLOC_COMPONENTS_VERBOSE=1
    -

    displays verbose information about components. Display messages when components are registered or enabled. This is the recommended way to list the available components with their priority (all of them are registered at startup).

    -

    -
    -
    HWLOC_PLUGINS_PATH=/path/to/hwloc/plugins/:...
    -

    changes the default search directory for plugins. By default, $libdir/hwloc is used. The variable may contain several colon-separated directories.

    -

    -
    -
    HWLOC_PLUGINS_VERBOSE=1
    -

    displays verbose information about plugins. List which directories are scanned, which files are loaded, and which components are successfully loaded.

    -

    -
    -
    HWLOC_PLUGINS_BLACKLIST=filename1,filename2,...
    -

    prevents plugins from being loaded if their filename (without path) is listed. Plugin filenames may be found in verbose messages outputted when HWLOC_PLUGINS_VERBOSE=1.

    -

    -
    -
    HWLOC_DEBUG_VERBOSE=0
    -

    disables all verbose messages that are enabled by default when –enable-debug is passed to configure. When set to more than 1, even more verbose messages are displayed. The default is 1.

    -

    -
    -
    -
    -
    - - - - - - -
    -
    -
    CPU and Memory Binding Overview
    -
    -
    -

    -

    -

    -

    Some operating systems do not systematically provide separate functions for CPU and memory binding. This means that CPU binding functions may have have effects on the memory binding policy. Likewise, changing the memory binding policy may change the CPU binding of the current thread. This is often not a problem for applications, so by default hwloc will make use of these functions when they provide better binding support.

    -

    If the application does not want the CPU binding to change when changing the memory policy, it needs to use the HWLOC_MEMBIND_NOCPUBIND flag to prevent hwloc from using OS functions which would change the CPU binding. Additionally, HWLOC_CPUBIND_NOMEMBIND can be passed to CPU binding function to prevent hwloc from using OS functions would change the memory binding policy. Of course, using these flags will reduce hwloc's overall support for binding, so their use is discouraged.

    -

    One can avoid using these flags but still closely control both memory and CPU binding by allocating memory, touching each page in the allocated memory, and then changing the CPU binding. The already-really-allocated memory will then be "locked" to physical memory and will not be migrated. Thus, even if the memory binding policy gets changed by the CPU binding order, the already-allocated memory will not change with it. When binding and allocating further memory, the CPU binding should be performed again in case the memory binding altered the previously-selected CPU binding.

    -

    Not all operating systems support the notion of a "current" memory binding policy for the current process, but such operating systems often still provide a way to allocate data on a given node set. Conversely, some operating systems support the notion of a "current" memory binding policy and do not permit allocating data on a specific node set without changing the current policy and allocate the data. To provide the most powerful coverage of these facilities, hwloc provides:

    -
      -
    • -functions that set/get the current memory binding policies (if supported): hwloc_set/get_membind() and hwloc_set/get_proc_membind()
      • -
    • -a function that allocates memory bound to specific node set without changing the current memory binding policy (if supported): hwloc_alloc_membind().
      • -
    • -a helper which, if needed, changes the current memory binding policy of the process in order to obtain memory binding: hwloc_alloc_membind_policy().
      • -
    -

    An application can thus use the two first sets of functions if it wants to manage separately the global process binding policy and directed allocation, or use the third set of functions if it does not care about the process memory binding policy.

    -

    See CPU binding and Memory binding for hwloc's API functions regarding CPU and memory binding, respectively. There are some examples under doc/examples/ in the source tree.

    -
    -
    - - - - - - -
    -
    -
    I/O Devices
    -
    -
    -

    -

    -

    -

    hwloc usually manipulates processing units and memory but it can also discover I/O devices and report their locality as well. This is useful for placing I/O intensive applications on cores near the I/O devices they use, or for gathering information about all platform components.

    -

    -

    -

    -

    -Enabling and requirements

    -

    I/O discovery is disabled by default (except in lstopo) for performance reasons. It can be enabled by changing the filtering of I/O object types to HWLOC_TYPE_FILTER_KEEP_IMPORTANT or HWLOC_TYPE_FILTER_KEEP_ALL before loading the topology, for instance with hwloc_topology_set_io_types_filter().

    -

    Note that I/O discovery requires significant help from the operating system. The pciaccess library (the development package is usually libpciaccess-devel or libpciaccess-dev) is needed to fully detect PCI devices and bridges/switches. On Linux, PCI discovery may still be performed even if libpciaccess cannot be used. But it misses PCI device names. Moreover, some operating systems require privileges for probing PCI devices, see Does hwloc require privileged access? for details.

    -

    The actual locality of I/O devices is only currently detected on Linux. Other operating system will just report I/O devices as being attached to the topology root object.

    -

    -

    -

    -

    -I/O objects

    -

    When I/O discovery is enabled and supported, some additional objects are added to the topology. The corresponding I/O object types are:

    -

    Any of these types may be filtered individually with hwloc_topology_set_type_filter().

    -

    hwloc tries to attach these new objects to normal objects (usually NUMA nodes) to match their actual physical location. For instance, if a I/O hub (or root complex) is physically connected to a package, the corresponding hwloc bridge object (and its PCI bridges and devices children) is inserted as a child of the corresponding hwloc Package object. These children are not in the normal children list but rather in the I/O-specific children list.

    -

    I/O objects also have neither CPU sets nor node sets (NULL pointers) because they are not directly usable by the user applications for binding. Moreover I/O hierarchies may be highly complex (asymmetric trees of bridges). So I/O objects are placed in specific levels with custom depths. Their lists may still be traversed with regular helpers such as hwloc_get_next_obj_by_type(). However, hwloc offers some dedicated helpers such as hwloc_get_next_pcidev() and hwloc_get_next_osdev() for convenience (see Finding I/O objects).

    -

    -

    -

    -

    -OS devices

    -

    Although each PCI device is uniquely identified by its bus ID (e.g. 0000:01:02.3), a user-space application can hardly find out which PCI device it is actually using. Applications rather use software handles (such as the eth0 network interface, the sda hard drive, or the mlx4_0 OpenFabrics HCA). Therefore hwloc tries to add software devices (HWLOC_OBJ_OS_DEVICE, also known as OS devices).

    -

    OS devices may be attached below PCI devices, but they may also be attached directly to normal objects. Indeed some OS devices are not related to PCI. For instance, NVDIMM block devices (such as pmem0s on Linux) are directly attached near their NUMA node (I/O child of the parent whose memory child is the NUMA node). Also, if hwloc could not discover PCI for some reason, PCI-related OS devices may also be attached directly to normal objects.

    -

    Finally, OS subdevices may be exposed as OS devices children of another OS device. This is the case of LevelZero subdevices for instance.

    -

    hwloc first tries to discover OS devices from the operating system, e.g. eth0, sda or mlx4_0. However, this ability is currently only available on Linux for some classes of devices.

    -

    hwloc then tries to discover software devices through additional I/O components using external libraries. For instance proprietary graphics drivers do not expose any named OS device, but hwloc may still create one OS object per software handle when supported. For instance the opencl and cuda components may add some opencl0d0 and cuda0 OS device objects.

    -

    Here is a list of OS device objects commonly created by hwloc components when I/O discovery is enabled and supported.

    -
      -
    • -Hard disks or non-volatile memory devices (HWLOC_OBJ_OSDEV_BLOCK)
        -
      • -sda or dax2.0 (Linux component)
        • -
      -
      • -
    • -Network interfaces (HWLOC_OBJ_OSDEV_NETWORK)
        -
      • -eth0, wlan0, ib0 (Linux component)
        • -
      • -hsn0 with "Slingshot" subtype for HPE Cray HSNs (Linux component).
        • -
      -
      • -
    • -OpenFabrics (InfiniBand, Omni-Path, usNIC, etc) HCAs (HWLOC_OBJ_OSDEV_OPENFABRICS)
        -
      • -mlx5_0, hfi1_0, qib0, usnic_0 (Linux component)
        • -
      • -bxi0 with "BXI" subtype for Atos/Bull BXI HCAs (Linux component) even if those are not really OpenFabrics.
        • -
      -
      • -
    • -GPUs (HWLOC_OBJ_OSDEV_GPU)
        -
      • -rsmi0 for the first RSMI device ("RSMI" subtype, from the RSMI component, using the AMD ROCm SMI library)
        • -
      • -nvml0 for the first NVML device ("NVML" subtype, from the NVML component, using the NVIDIA Management Library)
        • -
      • -:0.0 for the first display ("Display" subtype, from the GL component, using the NV-CONTROL X extension library, NVCtrl)
        • -
      • -card0 and renderD128 for DRM device files (from the Linux component, filtered-out by default because considered non-important)
        • -
      -
      • -
    • -Co-Processors (HWLOC_OBJ_OSDEV_COPROC)
        -
      • -opencl0d0 for the first device of the first OpenCL platform, opencl1d3 for the fourth device of the second OpenCL platform ("OpenCL" subtype, from the OpenCL component)
        • -
      • -ze0 for the first Level Zero device ("LevelZero" subtype, from the levelzero component, using the oneAPI Level Zero library), and ze0.1 for its second subdevice (if any).
        • -
      • -cuda0 for the first NVIDIA CUDA device ("CUDA" subtype, from the CUDA component, using the NVIDIA CUDA Library)
        • -
      • -ve0 for the first NEC Vector Engine device ("VectorEngine" subtype, from the Linux component)
        • -
      -
      • -
    • -DMA engine channel (HWLOC_OBJ_OSDEV_DMA) -
      • -
    -

    Note that some PCI devices may contain multiple software devices (see the example below).

    -

    See also Interoperability With Other Software for managing these devices without considering them as hwloc objects.

    -

    -

    -

    -

    -PCI devices and bridges

    -

    A PCI hierarchy is usually organized as follows: A hostbridge object ( HWLOC_OBJ_BRIDGE object with upstream type Host and downstream type PCI) is attached below a normal object (usually the entire machine or a NUMA node). There may be multiple hostbridges in the machine, attached to different places, but all PCI devices are below one of them (unless the Bridge object type is filtered-out).

    -

    Each hostbridge contains one or several children, either other bridges (usually PCI to PCI switches) or PCI devices (HWLOC_OBJ_PCI_DEVICE). The number of bridges between the hostbridge and a PCI device depends on the machine.

    -

    -

    -

    -

    -Consulting I/O devices and binding

    -

    I/O devices may be consulted by traversing the topology manually (with usual routines such as hwloc_get_obj_by_type()) or by using dedicated helpers (such as hwloc_get_pcidev_by_busid(), see Finding I/O objects).

    -

    I/O objects do not actually contain any locality information because their CPU sets and node sets are NULL. Their locality must be retrieved by walking up the object tree (through the parent link) until a non-I/O object is found (see hwloc_get_non_io_ancestor_obj()). This normal object should have non-NULL CPU sets and node sets which describe the processing units and memory that are immediately close to the I/O device. For instance the path from a OS device to its locality may go across a PCI device parent, one or several bridges, up to a Package node with the same locality.

    -

    Command-line tools are also aware of I/O devices. lstopo displays the interesting ones by default (passing --no-io disables it).

    -

    hwloc-calc and hwloc-bind may manipulate I/O devices specified by PCI bus ID or by OS device name.

      -
    • -pci=0000:02:03.0 is replaced by the set of CPUs that are close to the PCI device whose bus ID is given.
      • -
    • -os=eth0 is replaced by CPUs that are close to the I/O device whose software handle is called eth0.
      • -
    -

    This enables easy binding of I/O-intensive applications near the device they use.

    -

    -

    -

    -

    -Examples

    -

    The following picture shows a dual-package dual-core host whose PCI bus is connected to the first package and NUMA node.

    -
    - -
    -

    Six interesting PCI devices were discovered. However, hwloc found some corresponding software devices (eth0, eth1, sda, mlx4_0, ib0, and ib1) for only four of these physical devices. The other ones (PCI 102b:0532 and PCI 8086:3a20) are an unused IDE controller (no disk attached) and a graphic card (no corresponding software device reported to the user by the operating system).

    -

    On the contrary, it should be noted that three different software devices were found for the last PCI device (PCI 15b3:634a). Indeed this OpenFabrics HCA PCI device object contains one one OpenFabrics software device (mlx4_0) and two virtual network interface software devices (ib0 and ib1).

    -

    Here is the corresponding textual output:

    -
    Machine (24GB total)
-  Package L#0
-    NUMANode L#0 (P#0 12GB)
-    L3 L#0 (8192KB)
-      L2 L#0 (256KB) + L1 L#0 (32KB) + Core L#0 + PU L#0 (P#0)
-      L2 L#1 (256KB) + L1 L#1 (32KB) + Core L#1 + PU L#1 (P#2)
-    HostBridge
-      PCIBridge
-        PCI 01:00.0 (Ethernet)
-          Net "eth0"
-        PCI 01:00.1 (Ethernet)
-          Net "eth1"
-      PCIBridge
-        PCI 03:00.0 (RAID)
-          Block "sda"
-      PCIBridge
-        PCI 04:03.0 (VGA)
-      PCI 00:1f.2 (IDE)
-      PCI 51:00.0 (InfiniBand)
-        Net "ib0"
-        Net "ib1"
-        Net "mlx4_0"
-  Package L#1
-    NUMANode L#1 (P#1 12GB)
-    L3 L#1 (8192KB)
-      L2 L#2 (256KB) + L1 L#2 (32KB) + Core L#2 + PU L#2 (P#1)
-      L2 L#3 (256KB) + L1 L#3 (32KB) + Core L#3 + PU L#3 (P#3)
-
    -
    - - - - - - -
    -
    -
    Miscellaneous objects
    -
    -
    -

    -

    -

    -

    hwloc topologies may be annotated with Misc objects (of type HWLOC_OBJ_MISC) either automatically or by the user. This is a flexible way to annotate topologies with large sets of information since Misc objects may be inserted anywhere in the topology (to annotate specific objects or parts of the topology), even below other Misc objects, and each of them may contain multiple attributes (see also How do I annotate the topology with private notes?).

    -

    These Misc objects may have a subtype field to replace Misc with something else in the lstopo output.

    -

    -

    -

    -

    -Misc objects added by hwloc

    -

    hwloc only uses Misc objects when other object types are not sufficient, and when the Misc object type is not filtered-out anymore. This currently includes:

      -
    • -Memory modules (DIMMs), on Linux when privileged and when dmi-sysfs is supported by the kernel. These objects have a subtype field of value MemoryModule. They are currently always attached to the root object. Their attributes describe the DIMM vendor, model, etc. lstopo -v displays them as:
      Misc(MemoryModule) (P#1 DeviceLocation="Bottom-Slot 2(right)" BankLocation="BANK 2" Vendor=Elpida SerialNumber=21733667 AssetTag=9876543210 PartNumber="EBJ81UG8EFU0-GN-F ")
      -
      • -
    • -Displaying process binding in lstopo --top. These objects have a subtype field of value Process and a name attribute made of their PID and program name. They are attached below the object they are bound to. The textual lstopo displays them as:
      PU L#0 (P#0)
      -
      Misc(Process) 4445 myprogram
      -
      • -
    -

    -

    -

    -

    -Annotating topologies with Misc objects

    -

    The user may annotate hwloc topologies with its own Misc objects. This can be achieved with hwloc_topology_insert_misc_object() as well as hwloc-annotate command-line tool.

    -
    -
    - - - - - - -
    -
    -
    Object attributes
    -
    -
    -

    -

    -

    -

    -Normal attributes

    -

    hwloc objects have many generic attributes in the hwloc_obj structure, for instance their logical_index or os_index (see Should I use logical or physical/OS indexes? and how?), depth or name.

    -

    The kind of object is first described by the obj->type generic attribute (an integer). OS devices also have a specific obj->attr->osdev.type integer for distinguishing between NICs, GPUs, etc.

    -

    Objects may also have an optional obj->subtype pointing to a better description string (displayed by lstopo either in place or after the main obj->type attribute):

      -
    • -NUMA nodes: subtype DRAM (for usual main memory), HBM (high-bandwidth memory), SPM (specific-purpose memory, usually reserved for some custom applications), NVM (non-volatile memory when used as main memory), MCDRAM (on KNL) or GPUMemory (on POWER architecture with NVIDIA GPU memory shared over NVLink).
      • -
    • -Groups: subtype Cluster, Module, Tile, Compute Unit, Book or Drawer for different architecture-specific groups of CPUs (see also What are these Group objects in my topology?).
      • -
    • -OS devices (see also OS devices):
        -
      • -Co-processor: subtype OpenCL, LevelZero, CUDA, or VectorEngine.
        • -
      • -GPU: subtype RSMI (AMD GPU) or NVML (NVIDIA GPU).
        • -
      • -OpenFabrics: subtype BXI (Bull/Atos BXI HCA).
        • -
      • -Network: subtype Slingshot (HPE Cray Slingshot Cassini HSN).
        • -
      • -Block: subtype Disk, NVM (non-volatile memory), SPM (specific-purpose memory), CXLMem (CXL volatile ou persistent memory), Tape, or Removable Media Device.
        • -
      -
      • -
    • -L3 Caches: subtype MemorySideCache when hwloc is configured to expose the KNL MCDRAM in Cache mode as a L3.
      • -
    • -PCI devices: subtype NVSwitch for NVLink switches (see also NVLinkBandwidth in Distances).
      • -
    • -Misc devices: subtype MemoryModule (see also Misc objects added by hwloc)
      • -
    -

    Each object also contains an attr field that, if non NULL, points to a union hwloc_obj_attr_u of type-specific attribute structures. For instance, a L2Cache object obj contains cache-specific information in obj->attr->cache, such as its size and associativity, cache type. See hwloc_obj_attr_u for details.

    -

    -

    -

    -

    -Custom string infos

    -

    Aside os these generic attribute fields, hwloc annotates many objects with string attributes that are made of a key and a value. Each object contains a list of such pairs that may be consulted manually (looking at the object infos array field) or using the hwloc_obj_get_info_by_name(). The user may additionally add new key-value pairs to any object using hwloc_obj_add_info() or the hwloc-annotate program.

    -

    Here is a non-exhaustive list of attributes that may be automatically added by hwloc. Note that these attributes heavily depend on the ability of the operating system to report them. Many of them will therefore be missing on some OS.

    -

    -

    -

    -

    -Hardware Platform Information

    -

    These info attributes are attached to the root object (Machine).

    -
    -
    PlatformName, PlatformModel, PlatformVendor, PlatformBoardID, PlatformRevision,
    -
    -
    SystemVersionRegister, ProcessorVersionRegister (Machine)
    -
    Some POWER/PowerPC-specific attributes describing the platform and processor. Currently only available on Linux. Usually added to Package objects, but can be in Machine instead if hwloc failed to discover any package.
    -
    DMIBoardVendor, DMIBoardName, etc.
    -
    DMI hardware information such as the motherboard and chassis models and vendors, the BIOS revision, etc., as reported by Linux under /sys/class/dmi/id/.
    -
    MemoryMode, ClusterMode
    -

    Intel Xeon Phi processor configuration modes. Available if hwloc-dump-hwdata was used (see Why do I need hwloc-dump-hwdata for memory on Intel Xeon Phi processor?) or if hwloc managed to guess them from the NUMA configuration.

    -

    The memory mode may be Cache, Flat, Hybrid50 (half the MCDRAM is used as a cache) or Hybrid25 (25% of MCDRAM as cache). The cluster mode may be Quadrant, Hemisphere, All2All, SNC2 or SNC4. See doc/examples/get-knl-modes.c in the source directory for an example of retrieving these attributes.

    -
    -
    -

    -

    -

    -

    -Operating System Information

    -

    These info attributes are attached to the root object (Machine).

    -
    -
    OSName, OSRelease, OSVersion, HostName, Architecture
    -
    The operating system name, release, version, the hostname and the architecture name, as reported by the Unix uname command.
    -
    LinuxCgroup
    -
    The name the Linux control group where the calling process is placed.
    -
    WindowsBuildEnvironment
    -
    Either MinGW or Cygwin when one of these environments was used during build.
    -
    -

    -

    -

    -

    -hwloc Information

    -

    Unless specified, these info attributes are attached to the root object (Machine).

    -
    -
    Backend (topology root, or specific object added by that backend)
    -
    The name of the hwloc backend/component that filled the topology. If several components were combined, multiple Backend keys may exist, with different values, for instance x86 and Linux in the root object and CUDA in CUDA OS device objects.
    -
    SyntheticDescription
    -
    The description string that was given to hwloc to build this synthetic topology.
    -
    hwlocVersion
    -
    The version number of the hwloc library that was used to generate the topology. If the topology was loaded from XML, this is not the hwloc version that loaded it, but rather the first hwloc instance that exported the topology to XML earlier.
    -
    ProcessName
    -
    The name of the process that contains the hwloc library that was used to generate the topology. If the topology was from XML, this is not the hwloc process that loaded it, but rather the first process that exported the topology to XML earlier.
    -
    -

    -

    -

    -

    -CPU Information

    -

    These info attributes are attached to Package objects, or to the root object (Machine) if package locality information is missing.

    -
    -
    CPUModel
    -
    The processor model name.
    -
    CPUVendor, CPUModelNumber, CPUFamilyNumber, CPUStepping
    -
    The processor vendor name, model number, family number, and stepping number. Currently available for x86 and Xeon Phi processors on most systems, and for ia64 processors on Linux (except CPUStepping).
    -
    CPURevision
    -
    A POWER/PowerPC-specific general processor revision number, currently only available on Linux.
    -
    CPUType
    -
    A Solaris-specific general processor type name, such as "i86pc".
    -
    -

    -

    -

    -

    -OS Device Information

    -

    These info attributes are attached to OS device objects specified in parentheses.

    -
    -
    Vendor, Model, Revision, SerialNumber, Size, SectorSize (Block OS devices)
    -
    The vendor and model names, revision, serial number, size (in KiB = 1024 bytes) and SectorSize (in bytes).
    -
    LinuxDeviceID (Block OS devices)
    -
    The major/minor device number such as 8:0 of Linux device.
    -
    CXLRAMSize, CXLPMEMSize (CXL Memory Block OS devices)
    -
    The size of the volatile (RAM) or persistent (PMEM) memory in a CXL Type-3 device . Sizes are in KiB (1024 bytes).
    -
    GPUVendor, GPUModel (GPU or Co-Processor OS devices)
    -
    The vendor and model names of the GPU device.
    -
    OpenCLDeviceType, OpenCLPlatformIndex,
    -
    -
    OpenCLPlatformName, OpenCLPlatformDeviceIndex (OpenCL OS devices)
    -
    The type of OpenCL device, the OpenCL platform index and name, and the index of the device within the platform.
    -
    OpenCLComputeUnits, OpenCLGlobalMemorySize (OpenCL OS devices)
    -
    The number of compute units and global memory size of an OpenCL device. Sizes are in KiB (1024 bytes).
    -
    LevelZeroVendor, LevelZeroModel, LevelZeroBrand,
    -
    -
    LevelZeroSerialNumber, LevelZeroBoardNumber (LevelZero OS devices)
    -
    The name of the vendor, device model, brand of a Level Zero device, and its serial and board numbers.
    -
    LevelZeroDriverIndex, LevelZeroDriverDeviceIndex (LevelZero OS devices)
    -
    The index of the Level Zero driver within the list of drivers, and the index of the device within the list of devices managed by this driver.
    -
    LevelZeroUUID (LevelZero OS devices or subdevices)
    -
    The UUID of the device or subdevice.
    -
    LevelZeroSubdevices (LevelZero OS devices)
    -
    The number of subdevices below this OS device.
    -
    LevelZeroSubdeviceID (LevelZero OS subdevices)
    -
    The index of this subdevice within its parent.
    -
    LevelZeroDeviceType (LevelZero OS devices or subdevices)
    -
    A string describing the type of device, for instance "GPU", "CPU", "FPGA", etc.
    -
    LevelZeroNumSlices, LevelZeroNumSubslicesPerSlice,
    -
    -
    LevelZeroNumEUsPerSubslice, LevelZeroNumThreadsPerEU (LevelZero OS devices or subdevices)
    -
    The number of slices in the device, of subslices per slice, of execution units (EU) per subslice, and of threads per EU.
    -
    LevelZeroHBMSize, LevelZeroDDRSize, LevelZeroMemorySize (LevelZero OS devices or subdevices)
    -
    The amount of HBM or DDR memory of a LevelZero device or subdevice. Sizes are in KiB (1024 bytes). If the type of memory could not be determined, the generic name LevelZeroMemorySize is used. For devices that contain subdevices, the amount reported in the root device includes the memories of all its subdevices.
    -
    LevelZeroCQGroups, LevelZeroCQGroup2 (LevelZero OS devices or subdevices)
    -
    The number of completion queue groups, and the description of the third group (as N*0xX where N is the number of queues in the group, and 0xX is the hexadecimal bitmask of ze_command_queue_group_property_flag_t listing properties of those queues).
    -
    AMDUUID, AMDSerial (RSMI GPU OS devices)
    -
    The UUID and serial number of AMD GPUs.
    -
    RSMIVRAMSize, RSMIVisibleVRAMSize, RSMIGTTSize (RSMI GPU OS devices)
    -
    The amount of GPU memory (VRAM), of GPU memory that is visible from the host (Visible VRAM), and of system memory that is usable by the GPU (Graphics Translation Table). Sizes are in KiB (1024 bytes).
    -
    XGMIHiveID (RSMI GPU OS devices)
    -
    The ID of the group of GPUs (Hive) interconnected by XGMI links
    -
    XGMIPeers (RSMI GPU OS devices)
    -
    The list of RSMI OS devices that are directly connected to the current device through XGMI links. They are given as a space-separated list of object names, for instance rsmi2 rsmi3.
    -
    NVIDIAUUID, NVIDIASerial (NVML GPU OS devices)
    -
    The UUID and serial number of NVIDIA GPUs.
    -
    CUDAMultiProcessors, CUDACoresPerMP,
    -
    -
    CUDAGlobalMemorySize, CUDAL2CacheSize, CUDASharedMemorySizePerMP (CUDA OS devices)
    -
    The number of shared multiprocessors, the number of cores per multiprocessor, the global memory size, the (global) L2 cache size, and size of the shared memory in each multiprocessor of a CUDA device. Sizes are in KiB (1024 bytes).
    -
    VectorEngineModel, VectorEngineSerialNumber (VectorEngine OS devices)
    -
    The model and serial number of a VectorEngine device.
    -
    VectorEngineCores, VectorEngineMemorySize, VectorEngineLLCSize,
    -
    -
    VectorEngineL2Size, VectorEngineL1dSize, VectorEngineL1iSize (VectorEngine OS devices)
    -
    The number of cores, memory size, and the sizes of the (global) last level cache and of L2, L1d and L1i caches of a VectorEngine device. Sizes are in KiB (1024 bytes).
    -
    VectorEngineNUMAPartitioned (VectorEngine OS devices)
    -
    If this attribute exists, the VectorEngine device is configured in partitioned mode with multiple NUMA nodes.
    -
    Address, Port (Network interface OS devices)
    -
    The MAC address and the port number of a software network interface, such as eth4 on Linux.
    -
    NodeGUID, SysImageGUID, Port1State, Port2LID, Port2LMC, Port3GID1 (OpenFabrics OS devices)
    -
    The node GUID and GUID mask, the state of a port #1 (value is 4 when active), the LID and LID mask count of port #2, and GID #1 of port #3.
    -
    BXIUUID (OpenFabrics BXI OS devices)
    -
    The UUID of an Atos/Bull BXI HCA.
    -
    -

    -

    -

    -

    -Other Object-specific Information

    -

    These info attributes are attached to objects specified in parentheses.

    -
    -
    DAXDevice (NUMA Nodes)
    -
    The name of the Linux DAX device that was used to expose a non-volatile memory region as a volatile NUMA node.
    -
    DAXType (NUMA Nodes or DAX OS devices)
    -
    The type of memory exposed in a Linux DAX device or in the corresponding NUMA node, either "NVM" (non-volatile memory) or "SPM" (specific-purpose memory).
    -
    DAXParent (NUMA Nodes or DAX OS devices)
    -
    A string describing the Linux sysfs hierarchy that exposes the DAX device, for instance containing "hmem1" for specific-purpose memory or "ndbus0" for NVDIMMs.
    -
    -
    -
    PCIBusID (GPUMemory NUMA Nodes)
    -
    The PCI bus ID of the GPU whose memory is exposed in this NUMA node.
    -
    Inclusive (Caches)
    -
    The inclusiveness of a cache (1 if inclusive, 0 otherwise). Currently only available on x86 processors.
    -
    SolarisProcessorGroup (Group)
    -
    The Solaris kstat processor group name that was used to build this Group object.
    -
    PCIVendor, PCIDevice (PCI devices and bridges)
    -
    The vendor and device names of the PCI device.
    -
    PCISlot (PCI devices or Bridges)
    -
    The name/number of the physical slot where the device is plugged. If the physical device contains PCI bridges above the actual PCI device, the attribute may be attached to the highest bridge (i.e. the first object that actually appears below the physical slot).
    -
    Vendor, AssetTag, PartNumber, DeviceLocation, BankLocation (MemoryModule Misc objects)
    -
    Information about memory modules (DIMMs) extracted from SMBIOS.
    -
    -

    -

    -

    -

    -User-Given Information

    -

    Here is a non-exhaustive list of user-provided info attributes that have a special meaning:

    -
    lstopoStyle
    -
    Enforces the style of an object (background and text colors) in the graphical output of lstopo. See CUSTOM COLORS in the lstopo(1) manpage for details.
    -
    -
    -
    - - - - - - -
    -
    -
    Topology Attributes: Distances, Memory Attributes and CPU Kinds
    -
    -
    -

    -

    -

    -

    Besides the hierarchy of objects and individual object attributes (see Object attributes), hwloc may also expose finer information about the hardware organization.

    -

    -

    -

    -

    -Distances

    -

    A machine with 4 CPUs may have identical links between every pairs of CPUs, or those CPUs could also only be connected through a ring. In the ring case, accessing the memory of nearby CPUs is slower than local memory, but it is also faster than accessing the memory of CPU on the opposite side of the ring. These deep details cannot be exposed in the hwloc hierarchy, that is why hwloc also exposes distances.

    -

    Distances are matrices of values between sets of objects, usually latencies or bandwidths. By default, hwloc tries to get a matrix of relative latencies between NUMA nodes when exposed by the hardware.

    -

    In the aforementioned ring case, the matrix could report 10 for latency between a NUMA node and itself, 20 for nearby nodes, and 30 for nodes that are opposites on the ring. Those are theoretical values exposed by hardware vendors (in the System Locality Distance Information Table (SLIT) in the ACPI) rather than physical latencies. They are mostly meant for comparing node relative distances.

    -

    Distances structures currently created by hwloc are:

    -
    NUMALatency (Linux, Solaris, FreeBSD)
    -
    This is the matrix of theoretical latencies described above.
    -
    XGMIBandwidth (RSMI)
    -

    This is the matrix of unidirectional XGMI bandwidths between AMD GPUs (in MB/s). It contains 0 when there is no direct XGMI link between objects. Values on the diagonal are artificially set to very high so that local access always appears faster than remote access.

    -

    GPUs are identified by RSMI OS devices such as "rsmi0". They may be converted into the corresponding OpenCL or PCI devices using hwloc_get_obj_with_same_locality() or the hwloc-annotate tool.

    -

    hwloc_distances_transform() or hwloc-annotate may also be used to transform this matrix into something more convenient, for instance by replacing bandwidths with numbers of links between peers.

    -
    -
    XGMIHops (RSMI)
    -
    This matrix lists the number of XGMI hops between AMD GPUs. It reports 1 when there is a direct link between two distinct GPUs. If there is no XGMI route between them, the value is 0. The number of hops between a GPU and itself (on the diagonal) is 0 as well.
    -
    XeLinkBandwidth (LevelZero)
    -

    This is the matrix of unidirectional XeLink bandwidths between Intel GPUs (in MB/s). It contains 0 when there is no direct XeLink between objects. When there are multiple links, their bandwidth is aggregated.

    -

    Values on the diagonal are artificially set to very high so that local access always appears faster than remote access. This includes bandwidths between a (sub)device and itself, between a subdevice and its parent device, or between two subdevices of the same parent.

    -

    The matrix interconnects all LevelZero devices and subdevices (if any), even if some of them may have no link at all.

    -
    -
    NVLinkBandwidth (NVML)
    -

    This is the matrix of unidirectional NVLink bandwidths between NVIDIA GPUs (in MB/s). It contains 0 when there is no direct NVLink between objects. When there are multiple links, their bandwidth is aggregated. Values on the diagonal are artificially set to very high so that local access always appears faster than remote access.

    -

    On POWER platforms, NVLinks may also connects GPUs to CPUs. On NVIDIA platforms such as DGX-2, a NVSwitch may interconnect GPUs through NVLinks. In these cases, the distances structure is heterogeneous. GPUs always appear first in the matrix (as NVML OS devices such as "nvml0"), and non-GPU objects may appear at the end (Package for POWER processors, PCI device for NVSwitch).

    -

    NVML OS devices may be converted into the corresponding CUDA, OpenCL or PCI devices using hwloc_get_obj_with_same_locality() or the hwloc-annotate tool.

    -

    hwloc_distances_transform() or hwloc-annotate may also be used to transform this matrix into something more convenient, for instance by removing switches or CPU ports, or by replacing bandwidths with numbers of links between peers.

    -

    When a NVSwitch interconnects GPUs, only links between one GPU and different NVSwitch ports are reported. They may be merged into a single switch port with hwloc_distances_transform() or hwloc-annotate. Or a transitive closure may also be applied to report the bandwidth between GPUs across the NVSwitch.

    -
    -
    -

    Users may also specify their own matrices between any set of objects, even if these objects are of different types (e.g. bandwidths between GPUs and CPUs).

    -

    The entire API is located in hwloc/distances.h. See also Retrieve distances between objects, as well as Helpers for consulting distance matrices and Add distances between objects.

    -

    -

    -

    -

    -Memory Attributes

    -

    Machines with heterogeneous memory, for instance high-bandwidth memory (HBM), normal memory (DDR), and/or high-capacity slow memory (such as non-volatile memory DIMMs, NVDIMMs) require applications to allocate buffers in the appropriate target memory depending on performance and capacity needs. Those target nodes may be exposed in the hwloc hierarchy as different memory children but there is a need for performance information to select the appropriate one.

    -

    hwloc memory attributes are designed to expose memory information such as latency, bandwidth, etc. Users may also specify their own attributes and values.

    -

    The memory attributes API is located in hwloc/memattrs.h, see Comparing memory node attributes for finding where to allocate on and Managing memory attributes for details. See also an example in doc/examples/memory-attributes.c in the source tree.

    -

    -

    -

    -

    -CPU Kinds

    -

    Hybrid CPUs may contain different kinds of cores. The CPU kinds API in hwloc/cpukinds.h provides a way to list the sets of PUs in each kind and get some optional information about their hardware characteristics and efficiency.

    -

    If the operating system provides efficiency information (e.g. Windows 10, MacOS X / Darwin and some Linux kernels), it is used to rank hwloc CPU kinds by efficiency. Otherwise, hwloc implements several heuristics based on frequencies and core types (see HWLOC_CPUKINDS_RANKING in Environment Variables).

    -

    The ranking shows energy-efficient CPUs first, and high-performance power-hungry cores last.

    -

    These CPU kinds may be annotated with the following native attributes:

    -
    FrequencyMaxMHz (Linux)
    -
    The maximal operating frequency of the core, as reported by cpufreq drivers on Linux.
    -
    FrequencyBaseMHz (Linux)
    -
    The base operating frequency of the core, as reported by some cpufreq drivers on Linux (e.g. intel_pstate).
    -
    CoreType (x86)
    -
    A string describing the kind of core, currently IntelAtom or IntelCore, as reported by the x86 CPUID instruction on some Intel processors.
    -
    LinuxCapacity (Linux)
    -
    The Linux-specific CPU capacity found in sysfs, as reported by the Linux kernel on some recent platforms. Higher values usually mean that the Linux scheduler considers the core as high-performance rather than energy-efficient.
    -
    LinuxCPUType (Linux)
    -
    The Linux-specific CPU type found in sysfs, such as intel_atom_0, as reported by future Linux kernels on some Intel processors.
    -
    DarwinCompatible (Darwin / Mac OS X)
    -
    The compatibility attribute of the CPUs as found in the IO registry on Darwin / Mac OS X. For instance apple,icestorm;ARM,v8 for energy-efficient cores and apple,firestorm;ARM,v8 on performance cores on Apple M1 CPU.
    -
    -

    See Kinds of CPU cores for details.

    -
    -
    - - - - - - -
    -
    -
    Importing and exporting topologies from/to XML files
    -
    -
    -

    -

    -

    -

    hwloc offers the ability to export topologies to XML files and reload them later. This is for instance useful for loading topologies faster (see I do not want hwloc to rediscover my enormous machine topology every time I rerun a process), manipulating other nodes' topology, or avoiding the need for privileged processes (see Does hwloc require privileged access?).

    -

    Topologies may be exported to XML files thanks to hwloc_topology_export_xml(), or to a XML memory buffer with hwloc_topology_export_xmlbuffer(). The lstopo program can also serve as a XML topology export tool.

    -

    XML topologies may then be reloaded later with hwloc_topology_set_xml() and hwloc_topology_set_xmlbuffer(). The HWLOC_XMLFILE environment variable also tells hwloc to load the topology from the given XML file (see Environment Variables).

    -
    Note
    Loading XML topologies disables binding because the loaded topology may not correspond to the physical machine that loads it. This behavior may be reverted by asserting that loaded file really matches the underlying system with the HWLOC_THISSYSTEM environment variable or the HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM topology flag.
    -
    -The topology flag HWLOC_TOPOLOGY_FLAG_THISSYSTEM_ALLOWED_RESOURCES may be used to load a XML topology that contains the entire machine and restrict it to the part that is actually available to the current process (e.g. when Linux Cgroup/Cpuset are used to restrict the set of resources).
    -
    -hwloc also offers the ability to export/import Topology differences.
    -
    -XML topology files are not localized. They use a dot as a decimal separator. Therefore any exported topology can be reloaded on any other machine without requiring to change the locale.
    -
    -XML exports contain all details about the platform. It means that two very similar nodes still have different XML exports (e.g. some serial numbers or MAC addresses are different). If a less precise exporting/importing is required, one may want to look at Synthetic topologies instead.
    -

    -

    -

    -

    -libxml2 and minimalistic XML backends

    -

    hwloc offers two backends for importing/exporting XML.

    -

    First, it can use the libxml2 library for importing/exporting XML files. It features full XML support, for instance when those files have to be manipulated by non-hwloc software (e.g. a XSLT parser). The libxml2 backend is enabled by default if libxml2 development headers are available (the relevant development package is usually libxml2-devel or libxml2-dev).

    -

    If libxml2 is not available at configure time, or if --disable-libxml2 is passed, hwloc falls back to a custom backend. Contrary to the aforementioned full XML backend with libxml2, this minimalistic XML backend cannot be guaranteed to work with external programs. It should only be assumed to be compatible with the same hwloc release (even if using the libxml2 backend). Its advantage is, however, to always be available without requiring any external dependency.

    -

    If libxml2 is available but the core hwloc library should not directly depend on it, the libxml2 support may be built as a dynamicall-loaded plugin. One should pass --enable-plugins to enable plugin support (when supported) and build as plugins all component that support it. Or pass --enable-plugins=xml_libxml to only build this libxml2 support as a plugin.

    -

    -

    -

    -

    -XML import error management

    -

    Importing XML files can fail at least because of file access errors, invalid XML syntax, non-hwloc-valid XML contents, or incompatibilities between hwloc releases (see Are XML topology files compatible between hwloc releases?).

    -

    Both backend cannot detect all these errors when the input XML file or buffer is selected (when hwloc_topology_set_xml() or hwloc_topology_set_xmlbuffer() is called). Some errors such non-hwloc-valid contents can only be detected later when loading the topology with hwloc_topology_load().

    -

    It is therefore strongly recommended to check the return value of both hwloc_topology_set_xml() (or hwloc_topology_set_xmlbuffer()) and hwloc_topology_load() to handle all these errors.

    -
    -
    - - - - - - -
    -
    -
    Synthetic topologies
    -
    -
    -

    -

    -

    -

    hwloc may load fake or remote topologies so as to consult them without having the underlying hardware available. Aside from loading XML topologies, hwloc also enables the building of synthetic topologies that are described by a single string listing the arity of each levels.

    -

    For instance, lstopo may create a topology made of 2 packages, containing a single NUMA node and a L2 cache above two single-threaded cores:

    -
    $ lstopo -i "pack:2 node:1 l2:1 core:2 pu:1" -
-Machine (2048MB)
-  Package L#0
-    NUMANode L#0 (P#0 1024MB)
-    L2 L#0 (4096KB)
-      Core L#0 + PU L#0 (P#0)
-      Core L#1 + PU L#1 (P#1)
-  Package L#1
-    NUMANode L#1 (P#1 1024MB)
-    L2 L#1 (4096KB)
-      Core L#2 + PU L#2 (P#2)
-      Core L#3 + PU L#3 (P#3)
-

    Replacing - with file.xml in this command line will export this topology to XML as usual.

    -
    Note
    Synthetic topologies offer a very basic way to export a topology and reimport it on another machine. It is a lot less precise than XML but may still be enough when only the hierarchy of resources matters.
    -

    -

    -

    -

    -Synthetic description string

    -

    Each item in the description string gives the type of the level and the number of such children under each object of the previous level. That is why the above topology contains 4 cores (2 cores times 2 nodes).

    -

    These type names must be written as numanode, package, core, l2u, l1i, pu, group (hwloc_obj_type_sscanf() is used for parsing the type names). They do not need to be written case-sensitively, nor entirely (as long as there is no ambiguity, 2 characters such as ma select a Machine level). Note that I/O and Misc objects are not available.

    -

    Instead of specifying the type of each level, it is possible to just specify the arities and let hwloc choose all types according to usual topologies. The following examples are therefore equivalent: 

    $ lstopo -i "2 3 4 5 6"
-$ lstopo -i "Package:2 NUMANode:3 L2Cache:4 Core:5 PU:6"
-

    NUMA nodes are handled in a special way since they are not part of the main CPU hierarchy but rather attached below it as memory children. Thus, NUMANode:3 actually means Group:3 where one NUMA node is attached below each group. These groups are merged back into the parent when possible (typically when a single NUMA node is requested below each parent).

    -

    It is also possible the explicitly attach NUMA nodes to specific levels. For instance, a topology similar to a Intel Xeon Phi processor (with 2 NUMA nodes per 16-core group) may be created with: 

    $ lstopo -i "package:1 group:4 [numa] [numa] core:16 pu:4"
-

    The root object does not appear in the synthetic description string since it is always a Machine object. Therefore the Machine type is disallowed in the description as well.

    -

    A NUMA level (with a single NUMA node) is automatically added if needed.

    -

    Each item may be followed parentheses containing a list of space-separated attributes. For instance:

      -
    • -L2iCache:2(size=32kB) specifies 2 children of 32kB level-2 instruction caches. The size may be specified in bytes (without any unit suffix) or as kB, KiB, MB, MiB, etc.
      • -
    • -NUMANode:3(memory=16MB) specifies 3 NUMA nodes with 16MB each. The size may be specified in bytes (without any unit suffix) or as GB, GiB, TB, TiB, etc.
      • -
    • -PU:2(indexes=0,2,1,3) specifies 2 PU children and the full list of OS indexes among the entire set of 4 PU objects.
      • -
    • -PU:2(indexes=numa:core) specifies 2 PU children whose OS indexes are interleaved by NUMA node first and then by package.
      • -
    • -Attributes in parentheses at the very beginning of the description apply to the root object.
      • -
    -

    hwloc command-line tools may modify a synthetic topology, for instance to customize object attributes, or to remove some objects to make the topology heterogeneous or asymmetric. See many examples in How do I create a custom heterogeneous and asymmetric topology?.

    -

    -

    -

    -

    -Loading a synthetic topology

    -

    Aside from lstopo, the hwloc programming interface offers the same ability by passing the synthetic description string to hwloc_topology_set_synthetic() before hwloc_topology_load().

    -

    Synthetic topologies are created by the synthetic component. This component may be enabled by force by setting the HWLOC_SYNTHETIC environment variable to something such as node:2 core:3 pu:4.

    -

    Loading a synthetic topology disables binding support since the topology usually does not match the underlying hardware. Binding may be reenabled as usual by setting HWLOC_THISSYSTEM=1 in the environment or by setting the HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM topology flag.

    -

    -

    -

    -

    -Exporting a topology as a synthetic string

    -

    The function hwloc_topology_export_synthetic() may export a topology as a synthetic string. It offers a convenient way to quickly describe the contents of a machine. The lstopo tool may also perform such an export by forcing the output format.

    -
    $ lstopo --of synthetic --no-io
-Package:1 L3Cache:1 L2Cache:2 L1dCache:1 L1iCache:1 Core:1 PU:2
-

    The exported string may be passed back to hwloc for recreating another similar topology (see also Are synthetic strings compatible between hwloc releases?). The entire tree will be similar, but some attributes such as the processor model will be missing.

    -

    Such an export is only possible if the topology is totally symmetric. It means that the symmetric_subtree field of the root object is set. Also memory children should be attached in a symmetric way (e.g. the same number of memory children below each Package object, etc.). However, I/O devices and Misc objects are ignored when looking at symmetry and exporting the string.

    -
    -
    - - - - - - -
    -
    -
    Interoperability With Other Software
    -
    -
    -

    -

    -

    -

    Although hwloc offers its own portable interface, it still may have to interoperate with specific or non-portable libraries that manipulate similar kinds of objects. hwloc therefore offers several specific "helpers" to assist converting between those specific interfaces and hwloc.

    -

    Some external libraries may be specific to a particular OS; others may not always be available. The hwloc core therefore generally does not explicitly depend on these types of libraries. However, when a custom application uses or otherwise depends on such a library, it may optionally include the corresponding hwloc helper to extend the hwloc interface with dedicated helpers.

    -

    Most of these helpers use structures that are specific to these external libraries and only meaningful on the local machine. If so, the helper requires the input topology to match the current machine. Some helpers also require I/O device discovery to be supported and enabled for the current topology.

    -
    -
    Linux specific features
    -

    hwloc/linux.h offers Linux-specific helpers that utilize some non-portable features of the Linux system, such as binding threads through their thread ID ("tid") or parsing kernel CPU mask files. See Linux-specific helpers.

    -

    -
    -
    Windows specific features
    -

    hwloc/windows.h offers Windows-specific helpers to query information about Windows processor groups. See Windows-specific helpers.

    -

    -
    -
    Linux libnuma
    -

    hwloc/linux-libnuma.h provides conversion helpers between hwloc CPU sets and libnuma-specific types, such as bitmasks. It helps you use libnuma memory-binding functions with hwloc CPU sets. See Interoperability with Linux libnuma bitmask and Interoperability with Linux libnuma unsigned long masks.

    -

    -
    -
    Glibc
    -

    hwloc/glibc-sched.h offers conversion routines between Glibc and hwloc CPU sets in order to use hwloc with functions such as sched_getaffinity() or pthread_attr_setaffinity_np(). See Interoperability with glibc sched affinity.

    -

    -
    -
    OpenFabrics Verbs
    -

    hwloc/openfabrics-verbs.h helps interoperability with the OpenFabrics Verbs interface. For example, it can return a list of processors near an OpenFabrics device. It may also return the corresponding OS device hwloc object for further information (if I/O device discovery is enabled). See Interoperability with OpenFabrics.

    -

    -
    -
    OpenCL
    -

    hwloc/opencl.h enables interoperability with the OpenCL interface. Only the AMD and NVIDIA implementations currently offer locality information. It may return the list of processors near a GPU given as a cl_device_id. It may also return the corresponding OS device hwloc object for further information (if I/O device discovery is enabled). See Interoperability with OpenCL.

    -

    -
    -
    oneAPI Level Zero
    -

    hwloc/levelzero.h enables interoperability with the oneAPI Level Zero interface. It may return the list of processors near an accelerator or GPU. It may also return the corresponding OS device hwloc object for further information (if I/O device discovery is enabled). See Interoperability with the oneAPI Level Zero interface..

    -

    -
    -
    AMD ROCm SMI Library (RSMI)
    -

    hwloc/rsmi.h enables interoperability with the AMD ROCm SMI interface. It may return the list of processors near an AMD GPU. It may also return the corresponding OS device hwloc object for further information (if I/O device discovery is enabled). See Interoperability with the ROCm SMI Management Library.

    -

    -
    -
    NVIDIA CUDA
    -

    hwloc/cuda.h and hwloc/cudart.h enable interoperability with NVIDIA CUDA Driver and Runtime interfaces. For instance, it may return the list of processors near NVIDIA GPUs. It may also return the corresponding OS device hwloc object for further information (if I/O device discovery is enabled). See Interoperability with the CUDA Driver API and Interoperability with the CUDA Runtime API.

    -

    -
    -
    NVIDIA Management Library (NVML)
    -

    hwloc/nvml.h enables interoperability with the NVIDIA NVML interface. It may return the list of processors near a NVIDIA GPU given as a nvmlDevice_t. It may also return the corresponding OS device hwloc object for further information (if I/O device discovery is enabled). See Interoperability with the NVIDIA Management Library.

    -

    -
    -
    NVIDIA displays
    -

    hwloc/gl.h enables interoperability with NVIDIA displays using the NV-CONTROL X extension (NVCtrl library). If I/O device discovery is enabled, it may return the OS device hwloc object that corresponds to a display given as a name such as :0.0 or given as a port/device pair (server/screen). See Interoperability with OpenGL displays.

    -

    -
    -
    Taskset command-line tool
    -

    The taskset command-line tool is widely used for binding processes. It manipulates CPU set strings in a format that is slightly different from hwloc's one (it does not divide the string in fixed-size subsets and separates them with commas). To ease interoperability, hwloc offers routines to convert hwloc CPU sets from/to taskset-specific string format. See for instance hwloc_bitmap_taskset_snprintf() in The bitmap API.

    -

    Most hwloc command-line tools also support the --taskset option to manipulate taskset-specific strings.

    -

    -
    -
    -
    -
    - - - - - - -
    -
    -
    Thread Safety
    -
    -
    -

    -

    -

    -

    Like most libraries that mainly fill data structures, hwloc is not thread safe but rather reentrant: all state is held in a hwloc_topology_t instance without mutex protection. That means, for example, that two threads can safely operate on and modify two different hwloc_topology_t instances, but they should not simultaneously invoke functions that modify the same instance. Similarly, one thread should not modify a hwloc_topology_t instance while another thread is reading or traversing it. However, two threads can safely read or traverse the same hwloc_topology_t instance concurrently.

    -

    When running in multiprocessor environments, be aware that proper thread synchronization and/or memory coherency protection is needed to pass hwloc data (such as hwloc_topology_t pointers) from one processor to another (e.g., a mutex, semaphore, or a memory barrier). Note that this is not a hwloc-specific requirement, but it is worth mentioning.

    -

    For reference, hwloc_topology_t modification operations include (but may not be limited to):

    -
    -
    Creation and destruction
    -

    hwloc_topology_init(), hwloc_topology_load(), hwloc_topology_destroy() (see Topology Creation and Destruction) imply major modifications of the structure, including freeing some objects. No other thread cannot access the topology or any of its objects at the same time.

    -

    Also references to objects inside the topology are not valid anymore after these functions return.

    -

    -
    -
    Runtime topology modifications
    -

    hwloc_topology_insert_misc_object(), hwloc_topology_alloc_group_object(), and hwloc_topology_insert_group_object() (see Modifying a loaded Topology) may modify the topology significantly by adding objects inside the tree, changing the topology depth, etc.

    -

    hwloc_distances_add_commit() and hwloc_distances_remove() (see Add distances between objects) modify the list of distance structures in the topology, and the former may even insert new Group objects.

    -

    hwloc_memattr_register() and hwloc_memattr_set_value() (see Managing memory attributes) modify the memory attributes of the topology.

    -

    hwloc_topology_restrict() modifies the topology even more dramatically by removing some objects.

    -

    hwloc_topology_refresh() updates some internal cached structures. (see below).

    -

    Although references to former objects may still be valid after insertion or restriction, it is strongly advised to not rely on any such guarantee and always re-consult the topology to reacquire new instances of objects.

    -

    -
    -
    Consulting distances
    -

    hwloc_distances_get() and its variants are thread-safe except if the topology was recently modified (because distances may involve objects that were removed).

    -

    Whenever the topology is modified (see above), hwloc_topology_refresh() should be called in the same thread-safe context to force the refresh of internal distances structures. A call to hwloc_distances_get() may also refresh distances-related structures.

    -

    Once this refresh has been performed, multiple hwloc_distances_get() may then be performed concurrently by multiple threads.

    -

    -
    -
    Consulting memory attributes
    -

    Functions consulting memory attributes in hwloc/memattrs.h are thread-safe except if the topology was recently modified (because memory attributes may involve objects that were removed).

    -

    Whenever the topology is modified (see above), hwloc_topology_refresh() should be called in the same thread-safe context to force the refresh of internal memory attribute structures. A call to hwloc_memattr_get_value() or hwloc_memattr_get_targets() may also refresh internal structures for a given memory attribute.

    -

    Once this refresh has been performed, multiple functions consulting memory attributes may then be performed concurrently by multiple threads.

    -

    -
    -
    Locating topologies
    -

    hwloc_topology_set_* (see Topology Detection Configuration and Query) do not modify the topology directly, but they do modify internal structures describing the behavior of the upcoming invocation of hwloc_topology_load(). Hence, all of these functions should not be used concurrently.

    -

    -
    -
    -
    -
    - - - - - - -
    -
    -
    Components and plugins
    -
    -
    -

    -

    -

    -

    hwloc is organized in components that are responsible for discovering objects. Depending on the topology configuration, some components will be used (once enabled, they create a backend), some will be ignored.

    -

    The usual default is to enable the native operating system component, (e.g. linux or solaris) and the pci one. If available, an architecture-specific component (such as x86) may also improve the topology detection. Finally, some hardware-specific components (such as cuda or rsmi) may add information about GPUs, accelerators, etc.

    -

    If a XML topology is loaded, the xml discovery component will be used instead of all other components.

    -

    -

    -

    -

    -Components enabled by default

    -

    The hwloc core contains a list of components sorted by priority. Each one is enabled as long as it does not conflict with the previously enabled ones. This includes native operating system components, architecture-specific ones, and if available, I/O components such as pci.

    -

    Usually the native operating system component (when it exists, e.g. linux or aix) is enabled first. Then hwloc looks for an architecture specific component (e.g. x86). Finally there also exist a basic component (no_os) that just tries to discover the number of PUs in the system.

    -

    Each component discovers as much topology information as possible. Most of them, including most native OS components, do nothing unless the topology is still empty. Some others, such as x86 and pci, can complete and annotate what other backends found earlier. Discovery is performed by phases: CPUs are first discovered, then memory is attached, then PCI, etc.

    -

    Default priorities ensure that clever components are invoked first. Native operating system components have higher priorities, and are therefore invoked first, because they likely offer very detailed topology information. If needed, it will be later extended by architecture-specific information (e.g. from the x86 component).

    -

    If any configuration function such as hwloc_topology_set_xml() is used before loading the topology, the corresponding component is enabled first. Then, as usual, hwloc enables any other component (based on priorities) that does not conflict.

    -

    Certain components that manage a virtual topology, for instance XML topology import or synthetic topology description, conflict with all other components. Therefore, they may only be loaded (e.g. with hwloc_topology_set_xml()) if no other component is enabled.

    -

    The environment variable HWLOC_COMPONENTS_VERBOSE may be set to get verbose messages about available components (including their priority) and enabling as backends.

    -

    -

    -

    -

    -Selecting which components to use

    -

    If no topology configuration functions such as hwloc_topology_set_synthetic() have been called, components may be selected with environment variables such as HWLOC_XMLFILE, HWLOC_SYNTHETIC, HWLOC_FSROOT, or HWLOC_CPUID_PATH (see Environment Variables).

    -

    Finally, the environment variable HWLOC_COMPONENTS resets the list of selected components. If the variable is set and empty (or set to a single comma separating nothing, since some operating systems do not accept empty variables), the normal component priority order is used.

    -

    If the variable is set to x86 in this variable will cause the x86 component to take precedence over any other component, including the native operating system component. It is therefore loaded first, before hwloc tries to load all remaining non-conflicting components. In this case, x86 would take care of discovering everything it supports, instead of only completing what the native OS information. This may be useful if the native component is buggy on some platforms.

    -

    It is possible to prevent some components from being loaded by prefixing their name with - in the list. For instance x86,-pci will load the x86 component, then let hwloc load all the usual components except pci. A single component phase may also be blacklisted, for instance with -linux:io.

    -

    It is possible to prevent all remaining components from being loaded by placing stop in the environment variable. Only the components listed before this keyword will be enabled.

    -

    hwloc_topology_set_components() may also be used inside the program to prevent the loading of a specific component (or phases) for the target topology.

    -

    -

    -

    -

    -Loading components from plugins

    -

    Components may optionally be built as plugins so that the hwloc core library does not directly depend on their dependencies (for instance the libpciaccess library). Plugin support may be enabled with the --enable-plugins configure option. All components buildable as plugins will then be built as plugins. The configure option may be given a comma-separated list of component names to specify the exact list of components to build as plugins.

    -

    Plugins are built as independent dynamic libraries that are installed in $libdir/hwloc. All plugins found in this directory are loaded during topology_init() (unless blacklisted in HWLOC_PLUGINS_BLACKLIST, see Environment Variables). A specific list of directories (colon-separated) to scan may be specified in the HWLOC_PLUGINS_PATH environment variable.

    -

    Note that loading a plugin just means that the corresponding component is registered to the hwloc core. Components are then only enabled (as a backend) if the topology configuration requests it, as explained in the previous sections.

    -

    Also note that plugins should carefully be enabled and used when embedding hwloc in another project, see Embedding hwloc in Other Software for details.

    -

    -

    -

    -

    -Existing components and plugins

    -

    All components distributed within hwloc are listed below. The list of actually available components may be listed at running with the HWLOC_COMPONENTS_VERBOSE environment variable (see Environment Variables).

    -
    -
    linux
    -
    The official component for discovering CPU, memory and I/O devices on Linux. It discovers PCI devices without the help of external libraries such as libpciaccess, but requires the pci component for adding vendor/device names to PCI objects. It also discovers many kinds of Linux-specific OS devices.
    -
    aix, darwin, freebsd, hpux, netbsd, solaris, windows
    -
    Each officially supported operating system has its own native component, which is statically built when supported, and which is used by default.
    -
    x86
    -
    The x86 architecture (either 32 or 64 bits) has its own component that may complete or replace the previously-found CPU information. It is statically built when supported.
    -
    bgq
    -
    This component is specific to IBM BlueGene/Q compute node (running CNK). It is built and enabled by default when --host=powerpc64-bgq-linux is passed to configure (see How do I build hwloc for BlueGene/Q?).
    -
    no_os
    -
    A basic component that just tries to detect the number of processing units in the system. It mostly serves on operating systems that are not natively supported. It is always statically built.
    -
    pci
    -
    PCI object discovery uses the external libpciaccess library; see I/O Devices. It may also annotate existing PCI devices with vendor and device names. It may be built as a plugin.
    -
    opencl
    -
    The OpenCL component creates co-processor OS device objects such as opencl0d0 (first device of the first OpenCL platform) or opencl1d3 (fourth device of the second platform). Only the AMD and NVIDIA OpenCL implementations currently offer locality information. It may be built as a plugin.
    -
    rsmi
    -
    This component creates GPU OS device objects such as rsmi0 for describing AMD GPUs. It may be built as a plugin.
    -
    levelzero
    -
    This component creates co-processor OS device objects such as ze0 for describing oneAPI Level Zero devices. It may also create sub-OS-devices such as ze0.0 inside those devices. It may be built as a plugin.
    -
    cuda
    -
    This component creates co-processor OS device objects such as cuda0 that correspond to NVIDIA GPUs used with CUDA library. It may be built as a plugin.
    -
    nvml
    -
    Probing the NVIDIA Management Library creates OS device objects such as nvml0 that are useful for batch schedulers. It also detects the actual PCIe link bandwidth without depending on power management state and without requiring administrator privileges. It may be built as a plugin.
    -
    gl
    -
    Probing the NV-CONTROL X extension (NVCtrl library) creates OS device objects such as :0.0 corresponding to NVIDIA displays. They are useful for graphical applications that need to place computation and/or data near a rendering GPU. It may be built as a plugin.
    -
    synthetic
    -
    Synthetic topology support (see Synthetic topologies) is always built statically.
    -
    xml
    -
    XML topology import (see Importing and exporting topologies from/to XML files) is always built statically. It internally uses a specific class of components for the actual XML import/export routines (see libxml2 and minimalistic XML backends for details).
      -
    • -xml_nolibxml is a basic and hwloc-specific XML import/export. It is always statically built.
      • -
    • -xml_libxml relies on the external libxml2 library for provinding a feature-complete XML import/export. It may be built as a plugin.
      • -
    -
    -
    fake
    -
    A dummy plugin that does nothing but is used for debugging plugin support.
    -
    -
    -
    - - - - - - -
    -
    -
    Embedding hwloc in Other Software
    -
    -
    -

    -

    -

    -

    It can be desirable to include hwloc in a larger software package (be sure to check out the LICENSE file) so that users don't have to separately download and install it before installing your software. This can be advantageous to ensure that your software uses a known-tested/good version of hwloc, or for use on systems that do not have hwloc pre-installed.

    -

    When used in "embedded" mode, hwloc will:

    -
      -
    • not install any header files
      • -
    • not build any documentation files
      • -
    • not build or install any executables or tests
      • -
    • not build libhwloc.* – instead, it will build libhwloc_embedded.*
      • -
    -

    There are two ways to put hwloc into "embedded" mode. The first is directly from the configure command line:

    -
    shell$ ./configure --enable-embedded-mode ...
-

    The second requires that your software project uses the GNU Autoconf / Automake / Libtool tool chain to build your software. If you do this, you can directly integrate hwloc's m4 configure macro into your configure script. You can then invoke hwloc's configuration tests and build setup by calling a m4 macro (see below).

    -

    Although hwloc dynamic shared object plugins may be used in embedded mode, the embedder project will have to manually setup dlopen or libltdl in its build system so that hwloc can load its plugins at run time. Also, embedders should be aware of complications that can arise due to public and private linker namespaces (e.g., if the embedder project is loaded into a private namespace and then hwloc tries to dynamically load its plugins, such loading may fail since the hwloc plugins can't find the hwloc symbols they need). The embedder project is strongly advised not to use hwloc's dynamically loading plugins / dlopen / libltdl capability.

    -

    -

    -

    -

    -Using hwloc's M4 Embedding Capabilities

    -

    Every project is different, and there are many different ways of integrating hwloc into yours. What follows is one example of how to do it.

    -

    If your project uses recent versions Autoconf, Automake, and Libtool to build, you can use hwloc's embedded m4 capabilities. We have tested the embedded m4 with projects that use Autoconf 2.65, Automake 1.11.1, and Libtool 2.2.6b. Slightly earlier versions of may also work but are untested. Autoconf versions prior to 2.65 are almost certain to not work.

    -

    You can either copy all the config/hwloc*m4 files from the hwloc source tree to the directory where your project's m4 files reside, or you can tell aclocal to find more m4 files in the embedded hwloc's "config" subdirectory (e.g., add "-Ipath/to/embedded/hwloc/config" to your Makefile.am's ACLOCAL_AMFLAGS).

    -

    The following macros can then be used from your configure script (only HWLOC_SETUP_CORE must be invoked if using the m4 macros):

    -
      -

    • HWLOC_SETUP_CORE(config-dir-prefix, action-upon-success, action-upon-failure, print_banner_or_not): Invoke the hwloc configuration tests and setup the hwloc tree to build. The first argument is the prefix to use for AC_OUTPUT files – it's where the hwloc tree is located relative to $top_srcdir. Hence, if your embedded hwloc is located in the source tree at contrib/hwloc, you should pass [contrib/hwloc] as the first argument. If HWLOC_SETUP_CORE and the rest of configure completes successfully, then "make" traversals of the hwloc tree with standard Automake targets (all, clean, install, etc.) should behave as expected. For example, it is safe to list the hwloc directory in the SUBDIRS of a higher-level Makefile.am. The last argument, if not empty, will cause the macro to display an announcement banner that it is starting the hwloc core configuration tests.

      -

      HWLOC_SETUP_CORE will set the following environment variables and AC_SUBST them: HWLOC_EMBEDDED_CFLAGS, HWLOC_EMBEDDED_CPPFLAGS, and HWLOC_EMBEDDED_LIBS. These flags are filled with the values discovered in the hwloc-specific m4 tests, and can be used in your build process as relevant. The _CFLAGS, _CPPFLAGS, and _LIBS variables are necessary to build libhwloc (or libhwloc_embedded) itself.

      -

      HWLOC_SETUP_CORE also sets HWLOC_EMBEDDED_LDADD environment variable (and AC_SUBSTs it) to contain the location of the libhwloc_embedded.la convenience Libtool archive. It can be used in your build process to link an application or other library against the embedded hwloc library.

      -

      NOTE: If the HWLOC_SET_SYMBOL_PREFIX macro is used, it must be invoked before HWLOC_SETUP_CORE.

      -
      • -
    • HWLOC_BUILD_STANDALONE: HWLOC_SETUP_CORE defaults to building hwloc in an "embedded" mode (described above). If HWLOC_BUILD_STANDALONE is invoked *before* HWLOC_SETUP_CORE, the embedded definitions will not apply (e.g., libhwloc.la will be built, not libhwloc_embedded.la).
      • -
    • HWLOC_SET_SYMBOL_PREFIX(foo_): Tells the hwloc to prefix all of hwloc's types and public symbols with "foo_"; meaning that function hwloc_init() becomes foo_hwloc_init(). Enum values are prefixed with an upper-case translation if the prefix supplied; HWLOC_OBJ_CORE becomes FOO_hwloc_OBJ_CORE. This is recommended behavior if you are including hwloc in middleware – it is possible that your software will be combined with other software that links to another copy of hwloc. If both uses of hwloc utilize different symbol prefixes, there will be no type/symbol clashes, and everything will compile, link, and run successfully. If you both embed hwloc without changing the symbol prefix and also link against an external hwloc, you may get multiple symbol definitions when linking your final library or application.
      • -
    • HWLOC_SETUP_DOCS, HWLOC_SETUP_UTILS, HWLOC_SETUP_TESTS: These three macros only apply when hwloc is built in "standalone" mode (i.e., they should NOT be invoked unless HWLOC_BUILD_STANDALONE has already been invoked).
      • -
    • HWLOC_DO_AM_CONDITIONALS: If you embed hwloc in a larger project and build it conditionally with Automake (e.g., if HWLOC_SETUP_CORE is invoked conditionally), you must unconditionally invoke HWLOC_DO_AM_CONDITIONALS to avoid warnings from Automake (for the cases where hwloc is not selected to be built). This macro is necessary because hwloc uses some AM_CONDITIONALs to build itself, and AM_CONDITIONALs cannot be defined conditionally. Note that it is safe (but unnecessary) to call HWLOC_DO_AM_CONDITIONALS even if HWLOC_SETUP_CORE is invoked unconditionally. If you are not using Automake to build hwloc, this macro is unnecessary (and will actually cause errors because it invoked AM_* macros that will be undefined).
      • -
    -

    NOTE: When using the HWLOC_SETUP_CORE m4 macro, it may be necessary to explicitly invoke AC_CANONICAL_TARGET (which requires config.sub and config.guess) and/or AC_USE_SYSTEM_EXTENSIONS macros early in the configure script (e.g., after AC_INIT but before AM_INIT_AUTOMAKE). See the Autoconf documentation for further information.

    -

    Also note that hwloc's top-level configure.ac script uses exactly the macros described above to build hwloc in a standalone mode (by default). You may want to examine it for one example of how these macros are used.

    -

    -

    -

    -

    -Example Embedding hwloc

    -

    Here's an example of integrating with a larger project named sandbox that already uses Autoconf, Automake, and Libtool to build itself:

    -
    # First, cd into the sandbox project source tree
-shell$ cd sandbox
-shell$ cp -r /somewhere/else/hwloc-<version> my-embedded-hwloc
-shell$ edit Makefile.am
-  1. Add "-Imy-embedded-hwloc/config" to ACLOCAL_AMFLAGS
-  2. Add "my-embedded-hwloc" to SUBDIRS
-  3. Add "$(HWLOC_EMBEDDED_LDADD)" and "$(HWLOC_EMBEDDED_LIBS)" to 
-     sandbox's executable's LDADD line.  The former is the name of the 
-     Libtool convenience library that hwloc will generate.  The latter 
-     is any dependent support libraries that may be needed by 
-     $(HWLOC_EMBEDDED_LDADD).
-  4. Add "$(HWLOC_EMBEDDED_CFLAGS)" to AM_CFLAGS
-  5. Add "$(HWLOC_EMBEDDED_CPPFLAGS)" to AM_CPPFLAGS
-shell$ edit configure.ac
-  1. Add "HWLOC_SET_SYMBOL_PREFIX(sandbox_hwloc_)" line
-  2. Add "HWLOC_SETUP_CORE([my-embedded-hwloc], [happy=yes], [happy=no])" line
-  3. Add error checking for happy=no case
-shell$ edit sandbox.c
-  1. Add #include <hwloc.h>
-  2. Add calls to sandbox_hwloc_init() and other hwloc API functions
-

    Now you can bootstrap, configure, build, and run the sandbox as normal – all calls to "sandbox_hwloc_*" will use the embedded hwloc rather than any system-provided copy of hwloc.

    -
    -
    - - - - - - -
    -
    -
    Frequently Asked Questions (FAQ)
    -
    -
    -

    -

    -

    -

    -Concepts

    -

    -I only need binding, or the number of cores, why should I use hwloc ?

    -

    hwloc is its portable API that works on a variety of operating systems. It supports binding of threads, processes and memory buffers (see CPU binding and Memory binding). Even if some features are not supported on some systems, using hwloc is much easier than reimplementing your own portability layer.

    -

    Moreover, hwloc provides knowledge of cores and hardware threads. It offers easy ways to bind tasks to individual hardware threads, or to entire multithreaded cores, etc. See How may I ignore symmetric multithreading, hyper-threading, etc. in hwloc?. Most alternative software for binding do not even know whether each core is single-threaded, multithreaded or hyper-threaded. They would bind to individual threads without any way to know whether multiple tasks are in the same physical core.

    -

    However, using hwloc comes with an overhead since a topology must be loaded before gathering information and binding tasks or memory. Fortunately this overhead may be significantly reduced by filtering non-interesting information out of the topology, see What may I disable to make hwloc faster? below.

    -

    -What may I disable to make hwloc faster?

    -

    Building a hwloc topology on a large machine may be slow because the discovery of hundreds of hardware cores or threads takes time (especially when reading thousands of sysfs files on Linux). Ignoring some objects (for instance caches) that aren't useful to the current application may improve this overhead. One should also consider using XML (see I do not want hwloc to rediscover my enormous machine topology every time I rerun a process) to work around such issues.

    -

    Contrary to lstopo which enables most features (see Why is lstopo slow?), the default hwloc configuration is to keep all objects enabled except I/Os and instruction caches. This usually builds a very precise view of the CPU and memory subsystems, which may be reduced if some information is unneeded.

    -


    - The following code tells hwloc to build a much smaller topology that only contains Cores (explicitly filtered-in below), hardware threads (PUs, cannot be filtered-out), NUMA nodes (cannot be filtered-out), and the root object (usually a Machine; the root cannot be removed without breaking the tree):

    -
    hwloc_topology_t topology;
-hwloc_topology_init(&topology);
-/* filter everything out */
-hwloc_topology_set_all_types_filter(topology, HWLOC_TYPE_FILTER_KEEP_NONE);
-/* filter Cores back in */
-hwloc_topology_set_type_filter(topology, HWLOC_OBJ_CORE, HWLOC_TYPE_FILTER_KEEP_ALL);
-hwloc_topology_load(topology);
-

    However, one should remember that filtering such objects out removes locality information from the hwloc tree. For instance, we may not know anymore which PU is close to which NUMA node. This would be useful to applications that explicitly want to place specific memory buffers close to specific tasks. To ignore useless objects but keep those that bring locality/hierarchy information, applications may replace HWLOC_TYPE_FILTER_KEEP_NONE with HWLOC_TYPE_FILTER_KEEP_STRUCTURE above.

    -


    - Starting with hwloc 2.8, it is also possible to ignore distances between objects, memory performance attributes, and kinds of CPU cores, by setting topology flags before load: 

    [...]
-/* disable distances, memory attributes and CPU kinds */
-hwloc_topology_set_flags(topology, HWLOC_TOPOLOGY_FLAG_NO_DISTANCES
-                                   |HWLOC_TOPOLOGY_FLAG_NO_MEMATTRS
-                                   |HWLOC_TOPOLOGY_FLAG_NO_CPUKINDS);
-[...]
-hwloc_topology_load(topology);
-


    - Finally it is possible to prevent some hwloc components from being loaded and queried. If you are sure that the Linux (or x86) component is enough to discover everything you need, you may ask hwloc to disable all other components by setting something like HWLOC_COMPONENTS=linux,stop in the environment. See Components and plugins for details.

    -

    -Should I use logical or physical/OS indexes? and how?

    -

    One of the original reasons why hwloc was created is that physical/OS indexes (obj->os_index) are often crazy and unpredictable: processors numbers are usually non-contiguous (processors 0 and 1 are not physically close), they vary from one machine to another, and may even change after a BIOS or system update. These numbers make task placement hardly portable. Moreover some objects have no physical/OS numbers (caches), and some objects have non-unique numbers (core numbers are only unique within a socket). Physical/OS indexes are only guaranteed to exist and be unique for PU and NUMA nodes.

    -

    hwloc therefore introduces logical indexes (obj->logical_index) which are portable, contiguous and logically ordered (based on the resource organization in the locality tree). In general, one should only use logical indexes and just let hwloc do the internal conversion when really needed (when talking to the OS and hardware).

    -

    hwloc developers recommends that users do not use physical/OS indexes unless they really know what they are doing. The main reason for still using physical/OS indexes is when interacting with non-hwloc tools such as numactl or taskset, or when reading hardware information from raw sources such as /proc/cpuinfo.

    -

    lstopo options -l and -p may be used to switch between logical indexes (prefixed with L#) and physical/OS indexes (P#). Converting one into the other may also be achieved with hwloc-calc which may manipulate either logical or physical indexes as input or output. See also hwloc-calc.

    -
    # Convert PU with physical number 3 into logical number
-$ hwloc-calc -I pu --physical-input --logical-output pu:3
-5
-
-# Convert a set of NUMA nodes from logical to physical
-# (beware that the output order may not match the input order)
-$ hwloc-calc -I numa --logical-input --physical-output numa:2-3 numa:7
-0,2,5
-

    -hwloc is only a structural model, it ignores performance models, memory bandwidth, etc.?

    -

    hwloc is indeed designed to provide applications with a structural model of the platform. This is an orthogonal approach to describing the machine with performance models, for instance using memory bandwidth or latencies measured by benchmarks. We believe that both approaches are important for helping application make the most of the hardware.

    -

    For instance, on a dual-processor host with four cores each, hwloc clearly shows which four cores are together. Latencies between all pairs of cores of the same processor are likely identical, and also likely lower than the latency between cores of different processors. However, the structural model cannot guarantee such implementation details. On the other side, performance models would reveal such details without always clearly identifying which cores are in the same processor.

    -

    The focus of hwloc is mainly of the structural modeling side. However, hwloc lets user adds performance information to the topology through distances (see Distances), memory attributes (see Memory Attributes) or even custom annotations (see How do I annotate the topology with private notes?). hwloc may also use such distance information for grouping objects together (see hwloc only has a one-dimensional view of the architecture, it ignores distances? and What are these Group objects in my topology?).

    -

    -hwloc only has a one-dimensional view of the architecture, it ignores distances?

    -

    hwloc places all objects in a tree. Each level is a one-dimensional view of a set of similar objects. All children of the same object (siblings) are assumed to be equally interconnected (same distance between any of them), while the distance between children of different objects (cousins) is supposed to be larger.

    -

    Modern machines exhibit complex hardware interconnects, so this tree may miss some information about the actual physical distances between objects. The hwloc topology may therefore be annotated with distance information that may be used to build a more realistic representation (multi-dimensional) of each level. For instance, there can be a distance matrix that representing the latencies between any pair of NUMA nodes if the BIOS and/or operating system reports them.

    -

    For more information about the hwloc distances, see Distances.

    -

    -What are these Group objects in my topology?

    -

    hwloc comes with a set of predefined object types (Core, Package, NUMA node, Caches) that match the vast majority of hardware platforms. The HWLOC_OBJ_GROUP type was designed for cases where this set is not sufficient. Groups may be used anywhere to add more structure information to the topology, for instance to show that 2 out of 4 NUMA nodes are actually closer than the others. When applicable, the subtype field describes why a Group was actually added (see also Normal attributes).

    -

    hwloc currently uses Groups for the following reasons:

      -
    • -NUMA parents when memory locality does not match any existing object.
      • -
    • -I/O parents when I/O locality does not match any existing object.
      • -
    • -Distance-based groups made of close objects.
      • -
    • -AMD Bulldozer dual-core compute units (subtype is ComputeUnit, in the x86 backend), but these objects are usually merged with the L2 caches.
      • -
    • -Intel Extended Topology Enumeration levels (in the x86 backend).
      • -
    • -Windows processor groups when HWLOC_WINDOWS_PROCESSOR_GROUP_OBJS=1 is set in the environment (except if they contain exactly a single NUMA node, or a single Package, etc.).
      • -
    • -IBM S/390 "Books" on Linux (subtype is Book).
      • -
    • -Linux Clusters of CPUs (subtype is Cluster), for instance for ARM cores sharing of some internal cache or bus, or x86 cores sharing a L2 cache (since Linux kernel 5.16). HWLOC_DONT_MERGE_CLUSTER_GROUPS=1 may be set in the environment to disable the automerging of these groups with identical caches, etc.
      • -
    • -AIX unknown hierarchy levels.
      • -
    -

    hwloc Groups are only kept if no other object has the same locality information. It means that a Group containing a single child is merged into that child. And a Group is merged into its parent if it is its only child. For instance a Windows processor group containing a single NUMA node would be merged with that NUMA node since it already contains the relevant hierarchy information.

    -

    When inserting a custom Group with hwloc_hwloc_topology_insert_group_object(), this merging may be disabled by setting its dont_merge attribute.

    -

    -What happens if my topology is asymmetric?

    -

    hwloc supports asymmetric topologies even if most platforms are usually symmetric. For example, there could be different types of processors in a single machine, each with different numbers of cores, symmetric multithreading, or levels of caches.

    -

    In practice, asymmetric topologies are rare but occur for at least two reasons:

      -
    • -Intermediate groups may added for I/O affinity: on a 4-package machine, an I/O bus may be connected to 2 packages. These packages are below an additional Group object, while the other packages are not (see also What are these Group objects in my topology?).
      • -
    • -If only part of a node is available to the current process, for instance because the resource manager uses Linux Cgroups to restrict process resources, some cores (or NUMA nodes) will disappear from the topology (unless flag HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED was passed). On a 32-core machine where 12 cores were allocated to the process, this may lead to one CPU package with 8 cores, another one with only 4 cores, and two missing packages.
      • -
    -

    To understand how hwloc manages such cases, one should first remember the meaning of levels and cousin objects. All objects of the same type are gathered as horizontal levels with a given depth. They are also connected through the cousin pointers of the hwloc_obj structure. Object attribute (cache depth and type, group depth) are also taken in account when gathering objects as horizontal levels. To be clear: there will be one level for L1i caches, another level for L1d caches, another one for L2, etc.

    -

    If the topology is asymmetric (e.g., if a group is missing above some processors), a given horizontal level will still exist if there exist any objects of that type. However, some branches of the overall tree may not have an object located in that horizontal level. Note that this specific hole within one horizontal level does not imply anything for other levels. All objects of the same type are gathered in horizontal levels even if their parents or children have different depths and types.

    -

    See the diagram in Terms and Definitions for a graphical representation of such topologies.

    -

    Moreover, it is important to understand that a same parent object may have children of different types (and therefore, different depths). These children are therefore siblings (because they have the same parent), but they are not cousins (because they do not belong to the same horizontal level).

    -

    -What happens to my topology if I disable symmetric multithreading, hyper-threading, etc. in the system?

    -

    hwloc creates one PU (processing unit) object per hardware thread. If your machine supports symmetric multithreading, for instance Hyper-Threading, each Core object may contain multiple PU objects: 

    $ lstopo -
-...
-  Core L#0
-    PU L#0 (P#0)
-    PU L#1 (P#2)
-  Core L#1
-    PU L#2 (P#1)
-    PU L#3 (P#3)
-

    x86 machines usually offer the ability to disable hyper-threading in the BIOS. Or it can be disabled on the Linux kernel command-line at boot time, or later by writing in sysfs virtual files.

    -

    If you do so, the hwloc topology structure does not significantly change, but some PU objects will not appear anymore. No level will disappear, you will see the same number of Core objects, but each of them will contain a single PU now. The PU level does not disappear either (remember that hwloc topologies always contain a PU level at the bottom of the topology) even if there is a single PU object per Core parent. 

    $ lstopo -
-...
-  Core L#0
-    PU L#0 (P#0)
-  Core L#1
-    PU L#1 (P#1)
-

    -How may I ignore symmetric multithreading, hyper-threading, etc. in hwloc?

    -

    First, see What happens to my topology if I disable symmetric multithreading, hyper-threading, etc. in the system? for more information about multithreading.

    -

    If you need to ignore symmetric multithreading in software, you should likely manipulate hwloc Core objects directly: 

    /* get the number of cores */
-unsigned nbcores = hwloc_get_nbobjs_by_type(topology, HWLOC_OBJ_CORE);
-...
-/* get the third core below the first package */
-hwloc_obj_t package, core;
-package = hwloc_get_obj_by_type(topology, HWLOC_OBJ_PACKAGE, 0);
-core = hwloc_get_obj_inside_cpuset_by_type(topology, package->cpuset,
-                                           HWLOC_OBJ_CORE, 2);
-

    Whenever you want to bind a process or thread to a core, make sure you singlify its cpuset first, so that the task is actually bound to a single thread within this core (to avoid useless migrations). 

    /* bind on the second core */
-hwloc_obj_t core = hwloc_get_obj_by_type(topology, HWLOC_OBJ_CORE, 1);
-hwloc_cpuset_t set = hwloc_bitmap_dup(core->cpuset);
-hwloc_bitmap_singlify(set);
-hwloc_set_cpubind(topology, set, 0);
-hwloc_bitmap_free(set);
-

    With hwloc-calc or hwloc-bind command-line tools, you may specify that you only want a single-thread within each core by asking for their first PU object: 

    $ hwloc-calc core:4-7
-0x0000ff00
-$ hwloc-calc core:4-7.pu:0
-0x00005500
-

    When binding a process on the command-line, you may either specify the exact thread that you want to use, or ask hwloc-bind to singlify the cpuset before binding 

    $ hwloc-bind core:3.pu:0 -- echo "hello from first thread on core #3"
-hello from first thread on core #3
-...
-$ hwloc-bind core:3 --single -- echo "hello from a single thread on core #3"
-hello from a single thread on core #3
-

    -

    -

    -

    -Advanced

    -

    -I do not want hwloc to rediscover my enormous machine topology every time I rerun a process

    -

    Although the topology discovery is not expensive on common machines, its overhead may become significant when multiple processes repeat the discovery on large machines (for instance when starting one process per core in a parallel application). The machine topology usually does not vary much, except if some cores are stopped/restarted or if the administrator restrictions are modified. Thus rediscovering the whole topology again and again may look useless.

    -

    For this purpose, hwloc offers XML import/export and shared memory features.

    -

    XML lets you save the discovered topology to a file (for instance with the lstopo program) and reload it later by setting the HWLOC_XMLFILE environment variable. The HWLOC_THISSYSTEM environment variable should also be set to 1 to assert that loaded file is really the underlying system.

    -

    Loading a XML topology is usually much faster than querying multiple files or calling multiple functions of the operating system. It is also possible to manipulate such XML files with the C programming interface, and the import/export may also be directed to memory buffer (that may for instance be transmitted between applications through a package). See also Importing and exporting topologies from/to XML files.

    -
    Note
    The environment variable HWLOC_THISSYSTEM_ALLOWED_RESOURCES may be used to load a XML topology that contains the entire machine and restrict it to the part that is actually available to the current process (e.g. when Linux Cgroup/Cpuset are used to restrict the set of resources). See Environment Variables.
    -

    Shared-memory topologies consist in one process exposing its topology in a shared-memory buffer so that other processes (running on the same machine) may use it directly. This has the advantage of reducing the memory footprint since a single topology is stored in physical memory for multiple processes. However, it requires all processes to map this shared-memory buffer at the same virtual address, which may be difficult in some cases. This API is described in Sharing topologies between processes.

    -

    -How many topologies may I use in my program?

    -

    hwloc lets you manipulate multiple topologies at the same time. However, these topologies consume memory and system resources (for instance file descriptors) until they are destroyed. It is therefore discouraged to open the same topology multiple times.

    -

    Sharing a single topology between threads is easy (see Thread Safety) since the vast majority of accesses are read-only.

    -

    If multiple topologies of different (but similar) nodes are needed in your program, have a look at How to avoid memory waste when manipulating multiple similar topologies?.

    -

    -How to avoid memory waste when manipulating multiple similar topologies?

    -

    hwloc does not share information between topologies. If multiple similar topologies are loaded in memory, for instance the topologies of different identical nodes of a cluster, lots of information will be duplicated.

    -

    hwloc/diff.h (see also Topology differences) offers the ability to compute topology differences, apply or unapply them, or export/import to/from XML. However, this feature is limited to basic differences such as attribute changes. It does not support complex modifications such as adding or removing some objects.

    -

    -How do I annotate the topology with private notes?

    -

    Each hwloc object contains a userdata field that may be used by applications to store private pointers. This field is only valid during the lifetime of these container object and topology. It becomes invalid as soon the topology is destroyed, or as soon as the object disappears, for instance when restricting the topology. The userdata field is not exported/imported to/from XML by default since hwloc does not know what it contains. This behavior may be changed by specifying application-specific callbacks with hwloc_topology_set_userdata_export_callback() and hwloc_topology_set_userdata_import_callback().

    -

    Each object may also contain some info attributes (key name and value) that are setup by hwloc during discovery and that may be extended by the user with hwloc_obj_add_info() (see also Object attributes). Contrary to the userdata field which is unique, multiple info attributes may exist for each object, even with the same name. These attributes are always exported to XML. However, only character strings may be used as key names and values.

    -

    It is also possible to insert Misc objects with a custom name anywhere as a leaf of the topology (see Miscellaneous objects). And Misc objects may have their own userdata and info attributes just like any other object.

    -

    The hwloc-annotate command-line tool may be used for adding Misc objects and info attributes.

    -

    There is also a topology-specific userdata pointer that can be used to recognize different topologies by storing a custom pointer. It may be manipulated with hwloc_topology_set_userdata() and hwloc_topology_get_userdata().

    -

    -How do I create a custom heterogeneous and asymmetric topology?

    -

    Synthetic topologies (see Synthetic topologies) allow to create custom topologies but they are always symmetric: same numbers of cores in each package, same local NUMA nodes, same shared cache, etc. To create an asymmetric topology, for instance to simulate hybrid CPUs, one may want to start from a larger symmetric topology and restrict it.
    -

    -

    Assuming we want two packages, one with 4 dual-threaded cores, and one with 8 single-threaded cores, first we create a topology with two identical packages, each with 8 dual-threaded cores: 

    $ lstopo -i "pack:2 core:8 pu:2" topo.xml
-

    Then create the bitmask representing the PUs that we wish to keep and pass it to lstopo's restrict option: 

    $ hwloc-calc -i topo.xml pack:0.core:0-3.pu:0-1 pack:1.core:0-7.pu:0
-0x555500ff
-$ lstopo -i topo.xml --restrict 0x555500ff topo2.xml
-$ mv -f topo2.xml topo.xml
-

    To mark the cores of first package as Big (power hungry) and those of second package as Little (energy efficient), define CPU kinds: 

    $ hwloc-annotate topo.xml topo.xml -- none -- cpukind $(hwloc-calc -i topo.xml pack:0) 1 0 CoreType Big
-$ hwloc-annotate topo.xml topo.xml -- none -- cpukind $(hwloc-calc -i topo.xml pack:1) 0 0 CoreType Little
-


    -

    -

    A similar method may be used for heterogeneous memory. First we specify 2 NUMA nodes per package in our synthetic description: 

    $ lstopo -i "pack:2 [numa(memory=100GB)] [numa(memory=10GB)] core:8 pu:2" topo.xml
-

    Then remove the second node of first package: 

    $ hwloc-calc -i topo.xml --nodeset node:all ~pack:0.node:1
-0x0000000e
-$ lstopo -i topo.xml --restrict nodeset=0xe topo2.xml
-$ mv -f topo2.xml topo.xml
-

    Then make one large node even bigger: 

    $ hwloc-annotate topo.xml topo.xml -- pack:0.numa:0 -- size 200GB
-

    Now we have 200GB in first package, and 100GB+10GB in second package.
    -

    -

    Next we may specify that the small NUMA node (second of second package) is HBM while the large ones are DRAM: 

    $ hwloc-annotate topo.xml topo.xml -- pack:0.numa:0 pack:1.numa:0 -- subtype DRAM
-$ hwloc-annotate topo.xml topo.xml -- pack:1.numa:1 -- subtype HBM
-

    Finally we may define memory performance attributes to specify that the HBM bandwidth (200GB/s) from local cores is higher than the DRAM bandwidth (50GB/s): 

    $ hwloc-annotate topo.xml topo.xml -- pack:0.numa:0 -- memattr Bandwidth pack:0 50000
-$ hwloc-annotate topo.xml topo.xml -- pack:1.numa:0 -- memattr Bandwidth pack:1 50000
-$ hwloc-annotate topo.xml topo.xml -- pack:1.numa:1 -- memattr Bandwidth pack:1 200000
-


    -

    -

    There is currently no way to create or modify I/O devices attached to such fake topologies. There is also no way to have some partial levels, e.g. a L3 cache in one package but not in the other.
    -

    -

    More changes may obviously be performed by manually modifying the XML export file. Simple operations such as modifying object attributes (cache size, memory size info keypairs, etc.), moving I/O subtrees, moving Misc objects, or removing objects are easy to perform.

    -

    However, modifying CPU and Memory objects requires care since cpusets and nodesets are supposed to remain consistent between parents and children. Similarly, PCI bus IDs should remain consistent between bridges and children within an I/O subtree.

    -

    -

    -

    -

    -Caveats

    -

    -Why is lstopo slow?

    -

    lstopo enables most hwloc objects and discovery flags by default so that the output topology is as precise as possible (while hwloc disables many of them by default). This includes I/O device discovery through PCI libraries as well as external libraries such as NVML. To speed up lstopo, you may disable such features with command-line options such as --no-io.

    -

    When NVIDIA GPU probing is enabled (e.g. with CUDA or NVML), one may enable the Persistent mode (with nvidia-smi -pm 1) to avoid significant GPU wakeup and initialization overhead.

    -

    When AMD GPU discovery is enabled with OpenCL and hwloc is used remotely over ssh, some spurious round-trips on the network may significantly increase the discovery time. Forcing the DISPLAY environment variable to the remote X server display (usually :0) instead of only setting the COMPUTE variable may avoid this.

    -

    Also remember that these hwloc components may be disabled. At build-time, one may pass configure flags such as --disable-opencl, --disable-cuda, --disable-nvml, --disable-rsmi, and --disable-levelzero. At runtime, one may set the environment variable HWLOC_COMPONENTS=-opencl,-cuda,-nvml,-rsmi,-levelzero or call hwloc_topology_set_components().

    -

    Remember that these backends are disabled by default, except in lstopo. If hwloc itself is still too slow even after disabling all the I/O devices as explained above, see also What may I disable to make hwloc faster? for disabling even more features.

    -

    -Does hwloc require privileged access?

    -

    hwloc discovers the topology by querying the operating system. Some minor features may require privileged access to the operation system. For instance memory module discovery on Linux is reserved to root, and the entire PCI discovery on Solaris and BSDs requires access to some special files that are usually restricted to root (/dev/pci* or /devices/pci*).

    -

    To workaround this limitation, it is recommended to export the topology as a XML file generated by the administrator (with the lstopo program) and make it available to all users (see Importing and exporting topologies from/to XML files). It will offer all discovery information to any application without requiring any privileged access anymore. Only the necessary hardware characteristics will be exported, no sensitive information will be disclosed through this XML export.

    -

    This XML-based model also has the advantage of speeding up the discovery because reading a XML topology is usually much faster than querying the operating system again.

    -

    The utility hwloc-dump-hwdata is also involved in gathering privileged information at boot time and making it available to non-privileged users (note that this may require a specific SELinux MLS policy module). However, it only applies to Intel Xeon Phi processors for now (see Why do I need hwloc-dump-hwdata for memory on Intel Xeon Phi processor?). See also HWLOC_DUMPED_HWDATA_DIR in Environment Variables for details about the location of dumped files.

    -

    -What should I do when hwloc reports "operating system" warnings?

    -

    When the operating system reports invalid locality information (because of either software or hardware bugs), hwloc may fail to insert some objects in the topology because they cannot fit in the already built tree of resources. If so, hwloc will report a warning like the following. The object causing this error is ignored, the discovery continues but the resulting topology will miss some objects and may be asymmetric (see also What happens if my topology is asymmetric?).

    -
    ****************************************************************************
-* hwloc received invalid information from the operating system.
-*
-* L3 (cpuset 0x000003f0) intersects with NUMANode (P#0 cpuset 0x0000003f) without inclusion!
-* Error occurred in topology.c line 940
-*
-* Please report this error message to the hwloc user's mailing list,
-* along with the files generated by the hwloc-gather-topology script.
-*
-* hwloc will now ignore this invalid topology information and continue.
-****************************************************************************
-

    These errors are common on large AMD platforms because of BIOS and/or Linux kernel bugs causing invalid L3 cache information. In the above example, the hardware reports a L3 cache that is shared by 2 cores in the first NUMA node and 4 cores in the second NUMA node. That's wrong, it should actually be shared by all 6 cores in a single NUMA node. The resulting topology will miss some L3 caches.

    -

    If your application does not care about cache sharing, or if you do not plan to request cache-aware binding in your process launcher, you may likely ignore this error (and hide it by setting HWLOC_HIDE_ERRORS=1 in your environment).

    -

    Some platforms report similar warnings about conflicting Packages and NUMANodes.

    -

    On x86 hosts, passing HWLOC_COMPONENTS=x86 in the environment may workaround some of these issues by switching to a different way to discover the topology.

    -

    Upgrading the BIOS and/or the operating system may help. Otherwise, as explained in the message, reporting this issue to the hwloc developers (by sending the tarball that is generated by the hwloc-gather-topology script on this platform) is a good way to make sure that this is a software (operating system) or hardware bug (BIOS, etc).

    -

    See also Questions and Bugs. Opening an issue on GitHub automatically displays hints on what information you should provide when reporting such bugs.

    -

    -Why does Valgrind complain about hwloc memory leaks?

    -

    If you are debugging your application with Valgrind, you want to avoid memory leak reports that are caused by hwloc and not by your program.

    -

    hwloc itself is often checked with Valgrind to make sure it does not leak memory. However, some global variables in hwloc dependencies are never freed. For instance libz allocates its global state once at startup and never frees it so that it may be reused later. Some libxml2 global state is also never freed because hwloc does not know whether it can safely ask libxml2 to free it (the application may also be using libxml2 outside of hwloc).

    -

    These unfreed variables cause leak reports in Valgrind. hwloc installs a Valgrind suppressions file to hide them. You should pass the following command-line option to Valgrind to use it: 

      --suppressions=/path/to/hwloc-valgrind.supp
-

    -

    -

    -

    -Platform-specific

    -

    -How do I enable ROCm SMI and select which version to use?

    -

    hwloc enables ROCm SMI as soon as it finds its development headers and libraries on the system. This detection consists in looking in /opt/rocm by default. If a ROCm version was specified with --with-rocm-version=4.4.0 or in the ROCM_VERSION environment variable, then /opt/rocm-<version> is used instead. Finally, a specific installation path may be specified with --with-rocm=/path/to/rocm.

    -

    As usual, developer header and library paths may also be set through environment variables such as LIBRARY_PATH and C_INCLUDE_PATH.

    -

    To find out whether ROCm SMI was detected and enabled, look in Probe / display I/O devices at the end of the configure script output. Passing --enable-rsmi will also cause configure to fail if RSMI could not be found and enabled in hwloc.

    -

    -How do I enable CUDA and select which CUDA version to use?

    -

    hwloc enables CUDA as soon as it finds CUDA development headers and libraries on the system. This detection may be performed thanks to pkg-config but it requires hwloc to know which CUDA version to look for. This may be done by passing --with-cuda-version=11.0 to the configure script. Otherwise hwloc will also look for the CUDA_VERSION environment variable.

    -

    If pkg-config does not work, passing --with-cuda=/path/to/cuda to the configure script is another way to define the corresponding library and header paths. Finally, these paths may also be set through environment variables such as LIBRARY_PATH and C_INCLUDE_PATH.

    -

    These paths, either detected by pkg-config or given manually, will also be used to detect NVML and OpenCL libraries and enable their hwloc backends.

    -

    To find out whether CUDA was detected and enabled, look in Probe / display I/O devices at the end of the configure script output. Passing --enable-cuda will also cause configure to fail if CUDA could not be found and enabled in hwloc.

    -

    Note that --with-cuda=/nonexisting may be used to disable all dependencies that are installed by CUDA, i.e. the CUDA, NVML and NVIDIA OpenCL backends, since the given directory does not exist.

    -

    -How do I find the local MCDRAM NUMA node on Intel Xeon Phi processor?

    -

    Intel Xeon Phi processors introduced a new memory architecture by possibly having two distinct local memories: some normal memory (DDR) and some high-bandwidth on-package memory (MCDRAM). Processors can be configured in various clustering modes to have up to 4 Clusters. Moreover, each Cluster (quarter, half or whole processor) of the processor may have its own local parts of the DDR and of the MCDRAM. This memory and clustering configuration may be probed by looking at MemoryMode and ClusterMode attributes, see Hardware Platform Information and doc/examples/get-knl-modes.c in the source directory.

    -

    Starting with version 2.0, hwloc properly exposes this memory configuration. DDR and MCDRAM are attached as two memory children of the same parent, DDR first, and MCDRAM second if any. Depending on the processor configuration, that parent may be a Package, a Cache, or a Group object of type Cluster.

    -

    Hence cores may have one or two local NUMA nodes, listed by the core nodeset. An application may allocate local memory from a core by using that nodeset. The operating system will actually allocate from the DDR when possible, or fallback to the MCDRAM.

    -

    To allocate specifically on one of these memories, one should walk up the parent pointers until finding an object with some memory children. Looking at these memory children will give the DDR first, then the MCDRAM if any. Their nodeset may then be used for allocating or binding memory buffers.

    -

    One may also traverse the list of NUMA nodes until finding some whose cpuset matches the target core or PUs. The MCDRAM NUMA nodes may be identified thanks to the subtype field which is set to MCDRAM.

    -

    Command-line tools such as hwloc-bind may bind memory on the MCDRAM by using the hbm keyword. For instance, to bind on the first MCDRAM NUMA node:

    -
    $ hwloc-bind --membind --hbm numa:0 -- myprogram
-$ hwloc-bind --membind numa:0 -- myprogram
-

    -Why do I need hwloc-dump-hwdata for memory on Intel Xeon Phi processor?

    -

    Intel Xeon Phi processors may use the on-package memory (MCDRAM) as either memory or a memory-side cache (reported as a L3 cache by hwloc by default, see HWLOC_KNL_MSCACHE_L3 in Environment Variables). There are also several clustering modes that significantly affect the memory organization (see How do I find the local MCDRAM NUMA node on Intel Xeon Phi processor? for more information about these modes). Details about these are currently only available to privileged users. Without them, hwloc relies on a heuristic for guessing the modes.

    -

    The hwloc-dump-hwdata utility may be used to dump this privileged binary information into human-readable and world-accessible files that the hwloc library will later load. The utility should usually run as root once during boot, in order to update dumped information (stored under /var/run/hwloc by default) in case the MCDRAM or clustering configuration changed between reboots.

    -

    When SELinux MLS policy is enabled, a specific hwloc policy module may be required so that all users get access to the dumped files (in /var/run/hwloc by default). One may use hwloc policy files from the SELinux Reference Policy at https://github.com/TresysTechnology/refpolicy-contrib (see also the documentation at https://github.com/TresysTechnology/refpolicy/wiki/GettingStarted).

    -

    hwloc-dump-hwdata requires dmi-sysfs kernel module loaded.

    -

    The utility is currently unneeded on platforms without Intel Xeon Phi processors.

    -

    See HWLOC_DUMPED_HWDATA_DIR in Environment Variables for details about the location of dumped files.

    -

    -How do I build hwloc for BlueGene/Q?

    -

    IBM BlueGene/Q machines run a standard Linux on the login/frontend nodes and a custom CNK (Compute Node Kernel) on the compute nodes.

    -

    To discover the topology of a login/frontend node, hwloc should be configured as usual, without any BlueGene/Q-specific option.

    -

    However, one would likely rather discover the topology of the compute nodes where parallel jobs are actually running. If so, hwloc must be cross-compiled with the following configuration line: 

    ./configure --host=powerpc64-bgq-linux --disable-shared --enable-static \
-  CPPFLAGS='-I/bgsys/drivers/ppcfloor -I/bgsys/drivers/ppcfloor/spi/include/kernel/cnk/'
-

    CPPFLAGS may have to be updated if your platform headers are installed in a different directory.

    -

    -How do I build hwloc for Windows?

    -

    hwloc binary releases for Windows are available on the website download pages (as pre-built ZIPs for both 32bits and 64bits x86 platforms). However hwloc also offers several ways to build on Windows:

    -
      -
    • -The usual Unix build steps (configure, make and make install) work on the MSYS2/MinGW environment on Windows (the official hwloc binary releases are built this way). Some environment variables and options must be configured, see contrib/ci.inria.fr/job-3-mingw.sh in the hwloc repository for an example (used for nightly testing).
      • -
    • -hwloc also supports such Unix-like builds in Cygwin (environment for porting Unix code to Windows).
      • -
    • -Windows build is also possible with CMake (CMakeLists.txt available under contrib/windows-cmake/).
      • -
    • -hwloc also comes with an example of Microsoft Visual Studio solution (under contrib/windows/) that may serve as a base for custom builds.
      • -
    -

    -How to get useful topology information on NetBSD?

    -

    The NetBSD (and FreeBSD) backend uses x86-specific topology discovery (through the x86 component). This implementation requires CPU binding so as to query topology information from each individual processor. This means that hwloc cannot find any useful topology information unless user-level process binding is allowed by the NetBSD kernel. The security.models.extensions.user_set_cpu_affinity sysctl variable must be set to 1 to do so. Otherwise, only the number of processors will be detected.

    -

    -Why does binding fail on AIX?

    -

    The AIX operating system requires specific user capabilities for attaching processes to resource sets (CAP_NUMA_ATTACH). Otherwise functions such as hwloc_set_cpubind() fail (return -1 with errno set to EPERM).

    -

    This capability must also be inherited (through the additional CAP_PROPAGATE capability) if you plan to bind a process before forking another process, for instance with hwloc-bind.

    -

    These capabilities may be given by the administrator with: 

    chuser "capabilities=CAP_PROPAGATE,CAP_NUMA_ATTACH" <username>
-

    -

    -

    -

    -Compatibility between hwloc versions

    -

    -How do I handle API changes?

    -

    The hwloc interface is extended with every new major release. Any application using the hwloc API should be prepared to check at compile-time whether some features are available in the currently installed hwloc distribution.

    -

    For instance, to check whether the hwloc version is at least 2.0, you should use: 

    #include <hwloc.h>
-#if HWLOC_API_VERSION >= 0x00020000
-...
-#endif
-

    To check for the API of release X.Y.Z at build time, you may compare HWLOC_API_VERSION with (X<<16)+(Y<<8)+Z.

    -

    For supporting older releases that do not have HWLOC_OBJ_NUMANODE and HWLOC_OBJ_PACKAGE yet, you may use:

    -
    #include <hwloc.h>
-#if HWLOC_API_VERSION < 0x00010b00
-#define HWLOC_OBJ_NUMANODE HWLOC_OBJ_NODE
-#define HWLOC_OBJ_PACKAGE HWLOC_OBJ_SOCKET
-#endif
-

    Once a program is built against a hwloc library, it may also dynamically link with compatible libraries from other hwloc releases. The version of that runtime library may be queried with hwloc_get_api_version(). For instance, the following code enables the topology flag HWLOC_TOPOLOGY_FLAG_NO_DISTANCES when compiling on hwloc 2.8 or later, but it disables it at runtime if running on an older hwloc (otherwise hwloc_topology_set_flags() would fail).

    -
    unsigned long topology_flags = ...; /* wanted flags that were supported before 2.8 */
-#if HWLOC_API_VERSION >= 0x20800
-if (hwloc_get_api_version() >= 0x20800)
-  topology_flags |= HWLOC_TOPOLOGY_FLAG_NO_DISTANCES; /* wanted flags only supported in 2.8+ */
-#endif
-hwloc_topology_set_flags(topology, topology_flags);
-

    See also How do I handle ABI breaks? for using hwloc_get_api_version() for testing ABI compatibility.

    -

    -What is the difference between API and library version numbers?

    -

    HWLOC_API_VERSION is the version of the API. It changes when functions are added, modified, etc. However it does not necessarily change from one release to another. For instance, two releases of the same series (e.g. 2.0.3 and 2.0.4) usually have the same HWLOC_API_VERSION (0x00020000). However their HWLOC_VERSION strings are different ("2.0.3" and "2.0.4" respectively).

    -

    -How do I handle ABI breaks?

    -

    The hwloc interface was deeply modified in release 2.0 to fix several issues of the 1.x interface (see Upgrading to the hwloc 2.0 API and the NEWS file in the source directory for details). The ABI was broken, which means applications must be recompiled against the new 2.0 interface.

    -

    To check that you are not mixing old/recent headers with a recent/old runtime library, check the major revision number in the API version: 

    #include <hwloc.h>
-  unsigned version = hwloc_get_api_version();
-  if ((version >> 16) != (HWLOC_API_VERSION >> 16)) {
-    fprintf(stderr,
-           "%s compiled for hwloc API 0x%x but running on library API 0x%x.\n"
-           "You may need to point LD_LIBRARY_PATH to the right hwloc library.\n"
-           "Aborting since the new ABI is not backward compatible.\n",
-           callname, HWLOC_API_VERSION, version);
-    exit(EXIT_FAILURE);
-  }
-

    To specifically detect v2.0 issues: 

    #include <hwloc.h>
-#if HWLOC_API_VERSION >= 0x00020000
-  /* headers are recent */
-  if (hwloc_get_api_version() < 0x20000)
-    ... error out, the hwloc runtime library is older than 2.0 ...
-#else
-  /* headers are pre-2.0 */
-  if (hwloc_get_api_version() >= 0x20000)
-    ... error out, the hwloc runtime library is more recent than 2.0 ...
-#endif
-

    In theory, library sonames prevent linking with incompatible libraries. However custom hwloc installations or improperly configured build environments may still lead to such issues. Hence running one of the above (cheap) checks before initializing hwloc topology may be useful.

    -

    -Are XML topology files compatible between hwloc releases?

    -

    XML topology files are forward-compatible: a XML file may be loaded by a hwloc library that is more recent than the hwloc release that exported that file.

    -

    However, hwloc XMLs are not always backward-compatible: Topologies exported by hwloc 2.x cannot be imported by 1.x by default (see XML changes for working around such issues). There are also some corner cases where backward compatibility is not guaranteed because of changes between major releases (for instance 1.11 XMLs could not be imported in 1.10).

    -

    XMLs are exchanged at runtime between some components of the HPC software stack (for instance the resource managers and MPI processes). Building all these components on the same (cluster-wide) hwloc installation is a good way to avoid such incompatibilities.

    -

    -Are synthetic strings compatible between hwloc releases?

    -

    Synthetic strings (see Synthetic topologies) are forward-compatible: a synthetic string generated by a release may be imported by future hwloc libraries.

    -

    However they are often not backward-compatible because new details may have been added to synthetic descriptions in recent releases. Some flags may be given to hwloc_topology_export_synthetic() to avoid such details and stay backward compatible.

    -

    -Is it possible to share a shared-memory topology between different hwloc releases?

    -

    Shared-memory topologies (see Sharing topologies between processes) have strong requirements on compatibility between hwloc libraries. Adopting a shared-memory topology fails if it was exported by a non-compatible hwloc release. Releases with same major revision are usually compatible (e.g. hwloc 2.0.4 may adopt a topology exported by 2.0.3) but different major revisions may be incompatible (e.g. hwloc 2.1.0 cannot adopt from 2.0.x).

    -

    Topologies are shared at runtime between some components of the HPC software stack (for instance the resource managers and MPI processes). Building all these components on the same (system-wide) hwloc installation is a good way to avoid such incompatibilities.

    -
    -
    - - - - - - -
    -
    -
    Upgrading to the hwloc 2.0 API
    -
    -
    -

    -

    -

    -

    See Compatibility between hwloc versions for detecting the hwloc version that you are compiling and/or running against.

    -

    -

    -

    -

    -New Organization of NUMA nodes and Memory

    -

    -Memory children

    -

    In hwloc v1.x, NUMA nodes were inside the tree, for instance Packages contained 2 NUMA nodes which contained a L3 and several cache.

    -

    Starting with hwloc v2.0, NUMA nodes are not in the main tree anymore. They are attached under objects as Memory Children on the side of normal children. This memory children list starts at obj->memory_first_child and its size is obj->memory_arity. Hence there can now exist two local NUMA nodes, for instance on Intel Xeon Phi processors.

    -

    The normal list of children (starting at obj->first_child, ending at obj->last_child, of size obj->arity, and available as the array obj->children) now only contains CPU-side objects: PUs, Cores, Packages, Caches, Groups, Machine and System. hwloc_get_next_child() may still be used to iterate over all children of all lists.

    -

    Hence the CPU-side hierarchy is built using normal children, while memory is attached to that hierarchy depending on its affinity.

    -

    -Examples

    -
      -
    • -

      a UMA machine with 2 packages and a single NUMA node is now modeled as a "Machine" object with two "Package" children and one "NUMANode" memory children (displayed first in lstopo below): 

      Machine (1024MB total)
-  NUMANode L#0 (P#0 1024MB)
-  Package L#0
-    Core L#0 + PU L#0 (P#0)
-    Core L#1 + PU L#1 (P#1)
-  Package L#1
-    Core L#2 + PU L#2 (P#2)
-    Core L#3 + PU L#3 (P#3)
-

      -
      • -
    • -

      a machine with 2 packages with one NUMA node and 2 cores in each is now: 

      Machine (2048MB total)
-  Package L#0
-    NUMANode L#0 (P#0 1024MB)
-    Core L#0 + PU L#0 (P#0)
-    Core L#1 + PU L#1 (P#1)
-  Package L#1
-    NUMANode L#1 (P#1 1024MB)
-    Core L#2 + PU L#2 (P#2)
-    Core L#3 + PU L#3 (P#3)
-

      -
      • -
    • -

      if there are two NUMA nodes per package, a Group object may be added to keep cores together with their local NUMA node: 

      Machine (4096MB total)
-  Package L#0
-    Group0 L#0
-      NUMANode L#0 (P#0 1024MB)
-      Core L#0 + PU L#0 (P#0)
-      Core L#1 + PU L#1 (P#1)
-    Group0 L#1
-      NUMANode L#1 (P#1 1024MB)
-      Core L#2 + PU L#2 (P#2)
-      Core L#3 + PU L#3 (P#3)
-  Package L#1
-    [...]
-

      -
      • -
    • -if the platform has L3 caches whose localities are identical to NUMA nodes, Groups aren't needed: 
      Machine (4096MB total)
-  Package L#0
-    L3 L#0 (16MB)
-      NUMANode L#0 (P#0 1024MB)
-      Core L#0 + PU L#0 (P#0)
-      Core L#1 + PU L#1 (P#1)
-    L3 L#1 (16MB)
-      NUMANode L#1 (P#1 1024MB)
-      Core L#2 + PU L#2 (P#2)
-      Core L#3 + PU L#3 (P#3)
-  Package L#1
-    [...]
-
      • -
    -

    -NUMA level and depth

    -

    NUMA nodes are not in "main" tree of normal objects anymore. Hence, they don't have a meaningful depth anymore (like I/O and Misc objects). They have a virtual (negative) depth (HWLOC_TYPE_DEPTH_NUMANODE) so that functions manipulating depths and level still work, and so that we can still iterate over the level of NUMA nodes just like for any other level.

    -

    For instance we can still use lines such as 

    int depth = hwloc_get_type_depth(topology, HWLOC_OBJ_NUMANODE);
-hwloc_obj_t obj = hwloc_get_obj_by_type(topology, HWLOC_OBJ_NUMANODE, 4);
-hwloc_obj_t node = hwloc_get_next_obj_by_depth(topology, HWLOC_TYPE_DEPTH_NUMANODE, prev);
-

    The NUMA depth should not be compared with others. An unmodified code that still compares NUMA and Package depths (to find out whether Packages contain NUMA or the contrary) would now always assume Packages contain NUMA (because the NUMA depth is negative).

    -

    However, the depth of the Normal parents of NUMA nodes may be used instead. In the last example above, NUMA nodes are attached to L3 caches, hence one may compare the depth of Packages and L3 to find out that NUMA nodes are contained in Packages. This depth of parents may be retrieved with hwloc_get_memory_parents_depth(). However, this function may return HWLOC_TYPE_DEPTH_MULTIPLE on future platforms if NUMA nodes are attached to different levels.

    -

    -Finding Local NUMA nodes and looking at Children and Parents

    -

    Applications that walked up/down to find NUMANode parent/children must now be updated. Instead of looking directly for a NUMA node, one should now look for an object that has some memory children. NUMA node(s) will be attached there. For instance, when looking for a NUMA node above a given core core: 

    hwloc_obj_t parent = core->parent;
-while (parent && !parent->memory_arity)
-  parent = parent->parent; /* no memory child, walk up */
-if (parent)
-  /* use parent->memory_first_child (and its siblings if there are multiple local NUMA nodes) */
-

    The list of local NUMA nodes (usually a single one) is also described by the nodeset attribute of each object (which contains the physical indexes of these nodes). Iterating over the NUMA level is also an easy way to find local NUMA nodes: 

    hwloc_obj_t tmp = NULL;
-while ((tmp = hwloc_get_next_obj_by_type(topology, HWLOC_OBJ_NUMANODE, tmp)) != NULL) {
-  if (hwloc_bitmap_isset(obj->nodeset, tmp->os_index))
-    /* tmp is a NUMA node local to obj, use it */
-}
-

    Similarly finding objects that are close to a given NUMA nodes should be updated too. Instead of looking at the NUMA node parents/children, one should now find a Normal parent above that NUMA node, and then look at its parents/children as usual: 

    hwloc_obj_t tmp = obj->parent;
-while (hwloc_obj_type_is_memory(tmp))
-  tmp = tmp->parent;
-/* now use tmp instead of obj */
-

    To avoid such hwloc v2.x-specific and NUMA-specific cases in the code, a generic lookup for any kind of object, including NUMA nodes, might also be implemented by iterating over a level. For instance finding an object of type type which either contains or is included in object obj can be performed by traversing the level of that type and comparing CPU sets: 

    hwloc_obj_t tmp = NULL;
-while ((tmp = hwloc_get_next_obj_by_type(topology, type, tmp)) != NULL) {
-  if (hwloc_bitmap_intersects(tmp->cpuset, obj->cpuset))
-    /* tmp matches, use it */
-}
-

    This generic lookup works whenever type or obj are Normal or Memory objects since both have CPU sets. Moreover, it is compatible with the hwloc v1.x API.

    -

    -

    -

    -

    -4 Kinds of Objects and Children

    -

    -I/O and Misc children

    -

    I/O children are not in the main object children list anymore either. They are in the list starting at obj->io_first_child and its size is obj->io_arity.

    -

    Misc children are not in the main object children list anymore. They are in the list starting at obj->misc_first_child and its size is obj->misc_arity.

    -

    See hwloc_obj for details about children lists.

    -

    hwloc_get_next_child() may still be used to iterate over all children of all lists.

    -

    -Kinds of objects

    -

    Given the above, objects may now be of 4 kinds:

      -
    • -Normal (everything not listed below, including Machine, Package, Core, PU, CPU Caches, etc);
      • -
    • -Memory (currently NUMA nodes or Memory-side Caches), attached to parents as Memory children;
      • -
    • -I/O (Bridges, PCI and OS devices), attached to parents as I/O children;
      • -
    • -Misc objects, attached to parents as Misc children.
      • -
    -

    See hwloc_obj for details about children lists.

    -

    For a given object type, the kind may be found with hwloc_obj_type_is_normal(), hwloc_obj_type_is_memory(), hwloc_obj_type_is_normal(), or comparing with HWLOC_OBJ_MISC.

    -

    Normal and Memory objects have (non-NULL) CPU sets and nodesets, while I/O and Misc objects don't have any sets (they are NULL).

    -

    -

    -

    -

    -HWLOC_OBJ_CACHE replaced

    -

    Instead of a single HWLOC_OBJ_CACHE, there are now 8 types HWLOC_OBJ_L1CACHE, ..., HWLOC_OBJ_L5CACHE, HWLOC_OBJ_L1ICACHE, ..., HWLOC_OBJ_L3ICACHE.

    -

    Cache object attributes are unchanged.

    -

    hwloc_get_cache_type_depth() is not needed to disambiguate cache types anymore since new types can be passed to hwloc_get_type_depth() without ever getting HWLOC_TYPE_DEPTH_MULTIPLE anymore.

    -

    hwloc_obj_type_is_cache(), hwloc_obj_type_is_dcache() and hwloc_obj_type_is_icache() may be used to check whether a given type is a cache, data/unified cache or instruction cache.

    -

    -

    -

    -

    -allowed_cpuset and allowed_nodeset only in the main topology

    -

    Objects do not have allowed_cpuset and allowed_nodeset anymore. They are only available for the entire topology using hwloc_topology_get_allowed_cpuset() and hwloc_topology_get_allowed_nodeset().

    -

    As usual, those are only needed when the INCLUDE_DISALLOWED topology flag is given, which means disallowed objects are kept in the topology. If so, one may find out whether some PUs inside an object is allowed by checking 

    hwloc_bitmap_intersects(obj->cpuset, hwloc_topology_get_allowed_cpuset(topology))
-

    Replace cpusets with nodesets for NUMA nodes. To find out which ones, replace intersects() with and() to get the actual intersection.

    -

    -

    -

    -

    -Object depths are now signed int

    -

    obj->depth as well as depths given to functions such as hwloc_get_obj_by_depth() or returned by hwloc_topology_get_depth() are now signed int.

    -

    Other depth such as cache-specific depth attribute are still unsigned.

    -

    -

    -

    -

    -Memory attributes become NUMANode-specific

    -

    Memory attributes such as obj->memory.local_memory are now only available in NUMANode-specific attributes in obj->attr->numanode.local_memory.

    -

    obj->memory.total_memory is available in all objects as obj->total_memory.

    -

    See hwloc_obj_attr_u::hwloc_numanode_attr_s and hwloc_obj for details.

    -

    -

    -

    -

    -Topology configuration changes

    -

    The old ignoring API as well as several configuration flags are replaced with the new filtering API, see hwloc_topology_set_type_filter() and its variants, and hwloc_type_filter_e for details.

    -
      -
    • -

      hwloc_topology_ignore_type(), hwloc_topology_ignore_type_keep_structure() and hwloc_topology_ignore_all_keep_structure() are respectively superseded by 

      hwloc_topology_set_type_filter(topology, type, HWLOC_TYPE_FILTER_KEEP_NONE);
-hwloc_topology_set_type_filter(topology, type, HWLOC_TYPE_FILTER_KEEP_STRUCTURE);
-hwloc_topology_set_all_types_filter(topology, HWLOC_TYPE_FILTER_KEEP_STRUCTURE);
-

      Also, the meaning of KEEP_STRUCTURE has changed (only entire levels may be ignored, instead of single objects), the old behavior is not available anymore.

      -

      -
      • -
    • -

      HWLOC_TOPOLOGY_FLAG_ICACHES is superseded by 

      hwloc_topology_set_icache_types_filter(topology, HWLOC_TYPE_FILTER_KEEP_ALL);
-

      -
      • -
    • -

      HWLOC_TOPOLOGY_FLAG_WHOLE_IO, HWLOC_TOPOLOGY_FLAG_IO_DEVICES and HWLOC_TOPOLOGY_FLAG_IO_BRIDGES replaced.

      -

      To keep all I/O devices (PCI, Bridges, and OS devices), use: 

      hwloc_topology_set_io_types_filter(topology, HWLOC_TYPE_FILTER_KEEP_ALL);
-

      To only keep important devices (Bridges with children, common PCI devices and OS devices): 

      hwloc_topology_set_io_types_filter(topology, HWLOC_TYPE_FILTER_KEEP_IMPORTANT);
-

      -
      • -
    -

    -

    -

    -

    -XML changes

    -

    2.0 XML files are not compatible with 1.x

    -

    2.0 can load 1.x files, but only NUMA distances are imported. Other distance matrices are ignored (they were never used by default anyway).

    -

    2.0 can export 1.x-compatible files, but only distances attached to the root object are exported (i.e. distances that cover the entire machine). Other distance matrices are dropped (they were never used by default anyway).

    -

    Users are advised to negociate hwloc versions between exporter and importer: If the importer isn't 2.x, the exporter should export to 1.x. Otherwise, things should work by default.

    -

    Hence hwloc_topology_export_xml() and hwloc_topology_export_xmlbuffer() have a new flags argument. to force a hwloc-1.x-compatible XML export.

      -
    • -If both always support 2.0, don't pass any flag.
      • -
    • -When the importer uses hwloc 1.x, export with HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1. Otherwise the importer will fail to import.
      • -
    • -When the exporter uses hwloc 1.x, it cannot pass any flag, and a 2.0 importer can import without problem.
      • -
    -
    #if HWLOC_API_VERSION >= 0x20000
-   if (need 1.x compatible XML export)
-      hwloc_topology_export_xml(...., HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1);
-   else /* need 2.x compatible XML export */
-      hwloc_topology_export_xml(...., 0);
-#else
-   hwloc_topology_export_xml(....);
-#endif
-

    Additionally, hwloc_topology_diff_load_xml(), hwloc_topology_diff_load_xmlbuffer(), hwloc_topology_diff_export_xml(), hwloc_topology_diff_export_xmlbuffer() and hwloc_topology_diff_destroy() lost the topology argument: The first argument (topology) isn't needed anymore.

    -

    -

    -

    -

    -Distances API totally rewritten

    -

    The new distances API is in hwloc/distances.h.

    -

    Distances are not accessible directly from objects anymore. One should first call hwloc_distances_get() (or a variant) to retrieve distances (possibly with one call to get the number of available distances structures, and another call to actually get them). Then it may consult these structures, and finally release them.

    -

    The set of object involved in a distances structure is specified by an array of objects, it may not always cover the entire machine or so.

    -

    -

    -

    -

    -Return values of functions

    -

    Bitmap functions (and a couple other functions) can return errors (in theory).

    -

    Most bitmap functions may have to reallocate the internal bitmap storage. In v1.x, they would silently crash if realloc failed. In v2.0, they now return an int that can be negative on error. However, the preallocated storage is 512 bits, hence realloc will not even be used unless you run hwloc on machines with larger PU or NUMAnode indexes.

    -

    hwloc_obj_add_info(), hwloc_cpuset_from_nodeset() and hwloc_cpuset_from_nodeset() also return an int, which would be -1 in case of allocation errors.

    -

    -

    -

    -

    -Misc API changes

    - -

    -

    -

    -

    -API removals and deprecations

    -
      -
    • -

      HWLOC_OBJ_SYSTEM removed: The root object is always HWLOC_OBJ_MACHINE

      -

      -
      • -
    • -

      _membind_nodeset() memory binding interfaces deprecated: One should use the variant without _nodeset suffix and pass the HWLOC_MEMBIND_BYNODESET flag.

      -

      -
      • -
    • -

      HWLOC_MEMBIND_REPLICATE removed: no supported operating system supports it anymore.

      -

      -
      • -
    • -

      hwloc_obj_snprintf() removed because it was long-deprecated by hwloc_obj_type_snprintf() and hwloc_obj_attr_snprintf().

      -

      -
      • -
    • -

      hwloc_obj_type_sscanf() deprecated, hwloc_obj_type_of_string() removed.

      -

      -
      • -
    • -

      hwloc_cpuset_from/to_nodeset_strict() deprecated: Now useless since all topologies are NUMA. Use the variant without the _strict suffix

      -

      -
      • -
    • -

      hwloc_distribute() and hwloc_distributev() removed, deprecated by hwloc_distrib().

      -

      -
      • -
    • -

      The Custom interface (hwloc_topology_set_custom(), etc.) was removed, as well as the corresponding command-line tools (hwloc-assembler, etc.). Topologies always start with object with valid cpusets and nodesets.

      -

      -
      • -
    • -

      obj->online_cpuset removed: Offline PUs are simply listed in the complete_cpuset as previously.

      -

      -
      • -
    • -

      obj->os_level removed.

      -

      -
      • -
    -
    -
    - - - - - - -
    -
    -
    Network Locality (netloc)
    -
    -
    -

    -

    -

    -

    Portable abstraction of network topologies for high-performance computing.

    -

    The netloc documentation spans of these sections:

    -

    -

    -

    -

    -Netloc Summary

    -

    The Portable Network Locality (netloc) software package provides network topology discovery tools, and an abstract representation of those networks topologies for a range of network types and configurations. It is provided as a companion to the Portable Hardware Locality (hwloc) package. These two software packages work together to provide a comprehensive view of the HPC system topology, spanning from the processor cores in one server to the cores in another - including the complex network(s) in between.

    -

    Towards this end, netloc is divided into two sets of components. The first tools are for the admin to extract the information about the topology of the machines with topology discovery tools for each network type and discovery technique (called readers). The second set of tools is for the user to exploit the collected information: to display the topology or create a topology-aware mapping of the processes of an application.

    -
    - -
    -

    -

    -

    -

    -Supported Networks

    -

    For now, only InfiniBand (See Setup) is supported, but it is planned to be extended very soon.

    -

    -

    -

    -

    -Netloc Installation

    -

    The generic installation procedure for both hwloc and netloc is described in Installation.

    -

    Note that netloc is currently not supported on as many platforms as the original hwloc project. netloc is enabled by default when supported, or can be disabled by passing --disable-netloc to the configure command-line.

    -

    -

    -

    -

    -Setup

    -

    To use Netloc tools, we need two steps. The first step consists in getting information about network directly from tools distributed by manufacturers. For Infiniband, for instance, this operation needs privileges to access to the network device. For this step we have wrappers in Netloc that will call the right tools with the right options.

    -

    The second step will transform the raw files generated by manufacturer tools, into files in a format readable by Netloc tools, and that will not depend on network technologies.

    -

    To be clear, let's take an example with Infiniband. This first step is handled by netloc_ib_gather_raw that will call ibnetdiscover and ibroutes tools to generate the necessary raw data files. The step has to be run by an administrator, since the Infiniband tools need to access to the network device.

    -
    shell$ netloc_ib_gather_raw --help
-Usage: netloc_ib_gather_raw [options] <outdir>
-  Dumps topology information to <outdir>/ib-raw/
-  Subnets are guessed from the <outdir>/hwloc/ directory where
-  the hwloc XML exports of some nodes are stored.
-Options:
- --sudo
-    Pass sudo to internal ibnetdiscover and ibroute invocations.
-    Useful when the entire script cannot run as root.
- --hwloc-dir <dir>
-    Use <dir> instead of <outdir>/hwloc/ for hwloc XML exports.
- --force-subnet [<subnet>:]<board>:<port> to force the discovery
-    Do not guess subnets from hwloc XML exports.
-    Force discovery on local board <board> port <port>
-    and optionally force the subnet id <subnet>
-    instead of reading it from the first GID.
-    Examples: --force-subnet mlx4_0:1
-              --force-subnet fe80:0000:0000:0000:mlx4_0:1
- --ibnetdiscover /path/to/ibnetdiscover
- --ibroute /path/to/ibroute
-    Specify exact location of programs. Default is /usr/bin/<program>
- --sleep <n>
-    Sleep for <n> seconds between invocations of programs probing the network
- --ignore-errors
-    Ignore errors from ibnetdiscover and ibroute, assume their outputs are ok
- --force -f
-    Always rediscover to overwrite existing files without asking
- --verbose -v
-    Add verbose messages
- --dry-run
-    Do not actually run programs or modify anything
- --help -h
-    Show this help
-
-shell$ ./netloc_ib_gather_raw /home/netloc/data
-WARNING: Not running as root.
-Using /home/netloc/data/hwloc as hwloc lstopo XML directory.
-
-Exporting local node hwloc XML...
-  Running lstopo-no-graphics...
-
-Found 1 subnets in hwloc directory:
- Subnet fe80:0000:0000:0000 is locally accessible from board qib0 port 1.
-
-Looking at fe80:0000:0000:0000 (through local board qib0 port 1)...
- Running ibnetdiscover...
- Getting routes...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L112' LID 18...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L108' LID 20...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L102' LID 23...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L104' LID 25...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L106' LID 24...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L114' LID 22...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L116' LID 21...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L109' LID 12...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L111' LID 11...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L107' LID 13...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L103' LID 17...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L105' LID 16...
-  Running ibroute for switch 'QLogic 12800-180 GUID=0x00066a00e8001310 L113' LID 15...
-

    The second step, that can be done by a regular user, is done by the tool netloc_ib_extract_dats.

    -
    shell$ netloc_ib_extract_dats --help
-Usage: netloc_ib_extract_dats <path to input raw data files> <output path> [--hwloc-dir
-<hwloc xml path>]
-        hwloc-dir can be an absolute path or a relative path from output path
-
-shell$ netloc_ib_extract_dats /home/netloc/data/ib-raw /home/netloc/data/netloc \
-  --hwloc-dir ../hwloc
-Read subnet: fe80:0000:0000:0000
-2 partitions found
-        'node'
-        'admin'
-

    -

    -

    -

    -Topology display

    -

    Netloc provides a tool, netloc_draw.html, that displays a topology in a web browser, by using a JSON file.

    -

    -Generate the JSON file

    -

    In order to display a topology, Netloc needs to generate a JSON file corresponding to a topology. For this operation, the user must run netloc_draw_to_json.

    -
    shell$ netloc_draw_to_json --help
-Usage: netloc_draw_to_json <path to topology directory>
-
-shell$ netloc_draw_to_json /home/netloc/data/netloc
-

    The netloc_draw_to_json command will write a JSON file for each topology file found in the input directory. The output files, written also in the input directory, can be open by netloc_draw.html in a web browser.

    -

    -Using netloc_draw

    -

    Once the JSON file is opened, the rendering is generated by the Javascript vis library for computing the position of the nodes. From the interface, it is possible to search for a specific node, to color the nodes, to expand merged switches, to show statistics, to export as an image... The user can interact with the nodes by moving them. For now, there are bugs and other nodes might move too.

    -

    The placement of the nodes is done statically if the topology is detected as a tree. If not, vis.js will use physics to find good positions, and it can be very time consuming.

    -
    - -
    -
    -
    - - - - - - -
    -
    -
    Netloc with Scotch
    -
    -
    -

    -

    -

    -

    Scotch is a toolbox for graph partitioning [XXX], that can do mapping between a communication graph and an architecture. Netloc interfaces with Scotch, by getting the topology of the machine and building the Scotch architecture. It is also possible to directly build a mapping file that can be given to mpirun.

    -

    -

    -

    -

    -Introduction

    -

    Scotch is able to deal architectures to represent the topology of a complete machine. Scotch handles several types of topologies: complete graphs, hypercubes, fat trees, meshes, torus, and random graphs. Moreover, Scotch is able to manage parts of architectures that are called sub-architectures. Thus, from a complete architecture, we can create a sub-architecture that will represent the available resources of the complete machine.

    -

    -

    -

    -

    -Setup

    -

    The first step in order to use Netloc tools is to discover the network. For this task, we provide tools called netloc_gather that are wrappers to the dedicated tools provided by the manufacturer of the network, that generate the raw data given by the devices. This task needs privileges to access to the network devices. Once, this task is completed, the raw data is converted in a generic format independent to the fabric by extract_dats. Figure 1 shows how the different modules of Netloc are linked, and what are the tools provided by Netloc.

    -

    -

    -

    -

    -Tools and API

    -

    When the machine is discovered and all the needed files are generated as seen previously, a user can call the netlocscotch functions from the API and interact with Scotch.

    -

    -Build Scotch architectures

    -

    Netloc provides a function to export the built topology into the Scotch format. That will give the possibility to the user to play with the topology in Scotch. Since Netloc matches the discovered topology with known topologies, the Scotch architecture won’t be random graphs but known topologies also in Scotch that will lead to optimized graph algorithms. This function is called netlocscotch_build_arch.

    -

    When the network topology is a tree, the topology converted by netlocscotch is the complete topology of the machine containing intranode topologies from hwloc. In this case, merging the two levels results in a bigger tree. For other network topologies, the global graph created for Scotch is a generic graph since it is not (at this moment) possible to create nested known architectures.

    -

    -Build Scotch sub-architectures

    -

    Most of the time, the user does not have access to the complete machine. He uses a resource manager to run his application and he will gain access only to a set of nodes. In this case getting the Scotch architecture of the complete machine is not relevant. Fortunately, Netloc is also able to build a Scotch sub-architecture that will contain only the available nodes. For this operation the user needs to run a specific program, netloc_get_resources, that will record in a file, the lists of available nodes and available cores by using MPI and hwloc. From this file, the function netlocscotch_build_subarch will build the Scotch sub-architecture.

    -

    -Mapping of processes

    -

    A main goal in having all these data about the network topology, especially in Scotch structures, is to help the process placement. For that, we use the mapping of a process graph to the architecture provided by Scotch. As we have seen previously, Netloc is able to detect the structure of the topology and will build the adapted Scotch architecture that will be more efficient than a random structure.

    -

    In case, the network topology is not a tree, netlocscotch converts the complete topology into a generic graph. The drawback in that is the Scotch graph algorithms are less efficient. To overcome that, netlocscotch does two steps of mapping: first it maps the processes to the nodes, and then for each node maps the processes to the cores. We have to conduct tests to check if the method gives better results than using a generic graph directly.

    -

    The other input needed in Scotch is the process graph. Since we want to optimize the placement to decrease the communication time, a good metric for building the application graph is the amount of communications between all pairs of processes. Studies still have to be done to choose, in the most efficient way, what we take into account to define the amount of communications between the number of messages, the size of messages... This information will be transformed into a process graph.

    -

    Once we have a good mapping computed by Scotch, we can give it to the user, or Netloc can even generate the corresponding rank file useful to MPI.

    -
    -
    - - - - - - -
    -
    -
    Data Structures
    -
    -
    -
    Here are the data structures with brief descriptions:
    -
    [detail level 123]
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     Chwloc_backendDiscovery backend structure
     Chwloc_cl_device_topology_amd
     Chwloc_componentGeneric component structure
     Chwloc_disc_componentDiscovery component structure
     Chwloc_disc_statusDiscovery status structure
     Chwloc_distances_sMatrix of distances between a set of objects
     Chwloc_info_sObject info
     ▼Chwloc_locationWhere to measure attributes from
     Chwloc_location_uActual location
     Chwloc_objStructure of a topology object
     ▼Chwloc_obj_attr_uObject type-specific Attributes
     Chwloc_bridge_attr_sBridge specific Object Attributes
     Chwloc_cache_attr_sCache-specific Object Attributes
     Chwloc_group_attr_sGroup-specific Object Attributes
     ▼Chwloc_numanode_attr_sNUMA node-specific Object Attributes
     Chwloc_memory_page_type_sArray of local memory page types, NULL if no local memory and page_types is 0
     Chwloc_osdev_attr_sOS Device specific Object Attributes
     Chwloc_pcidev_attr_sPCI Device specific Object Attributes
     Chwloc_topology_cpubind_supportFlags describing actual PU binding support for this topology
     ▼Chwloc_topology_diff_obj_attr_uOne object attribute difference
     Chwloc_topology_diff_obj_attr_generic_s
     Chwloc_topology_diff_obj_attr_string_sString attribute modification with an optional name
     Chwloc_topology_diff_obj_attr_uint64_sInteger attribute modification with an optional index
     ▼Chwloc_topology_diff_uOne element of a difference list between two topologies
     Chwloc_topology_diff_generic_s
     Chwloc_topology_diff_obj_attr_s
     Chwloc_topology_diff_too_complex_s
     Chwloc_topology_discovery_supportFlags describing actual discovery support for this topology
     Chwloc_topology_membind_supportFlags describing actual memory binding support for this topology
     Chwloc_topology_misc_supportFlags describing miscellaneous features
     Chwloc_topology_supportSet of flags describing actual support for this topology
    -
    -
    - - - - - - - -
    -
    Data Structure Index
    -
    -
    -
    H
    -
    -
    -
    H
    -
    hwloc_backend
    hwloc_obj_attr_u::hwloc_bridge_attr_s
    hwloc_obj_attr_u::hwloc_cache_attr_s
    hwloc_cl_device_topology_amd
    hwloc_component
    hwloc_disc_component
    hwloc_disc_status
    hwloc_distances_s
    hwloc_obj_attr_u::hwloc_group_attr_s
    hwloc_info_s
    hwloc_location
    hwloc_location::hwloc_location_u
    hwloc_obj_attr_u::hwloc_numanode_attr_s::hwloc_memory_page_type_s
    hwloc_obj_attr_u::hwloc_numanode_attr_s
    hwloc_obj
    hwloc_obj_attr_u
    hwloc_obj_attr_u::hwloc_osdev_attr_s
    hwloc_obj_attr_u::hwloc_pcidev_attr_s
    hwloc_topology_cpubind_support
    hwloc_topology_diff_u::hwloc_topology_diff_generic_s
    hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_generic_s
    hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s
    hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s
    hwloc_topology_diff_obj_attr_u
    hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s
    hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s
    hwloc_topology_diff_u
    hwloc_topology_discovery_support
    hwloc_topology_membind_support
    hwloc_topology_misc_support
    hwloc_topology_support
    -
    -
    - - - - - - - - -
    -
    hwloc Directory Reference
    -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

    -Files

    file  bitmap.h [code]
     
    file  cpukinds.h [code]
     
    file  cuda.h [code]
     
    file  cudart.h [code]
     
    file  diff.h [code]
     
    file  distances.h [code]
     
    file  export.h [code]
     
    file  gl.h [code]
     
    file  glibc-sched.h [code]
     
    file  helper.h [code]
     
    file  levelzero.h [code]
     
    file  linux-libnuma.h [code]
     
    file  linux.h [code]
     
    file  memattrs.h [code]
     
    file  nvml.h [code]
     
    file  opencl.h [code]
     
    file  openfabrics-verbs.h [code]
     
    file  plugins.h [code]
     
    file  rsmi.h [code]
     
    file  shmem.h [code]
     
    file  windows.h [code]
     
    -
    - - - - - - - - -
    -
    include Directory Reference
    -
    -
    - - - - -

    -Directories

    directory  hwloc
     
    - - - - - -

    -Files

    file  hwloc.h [code]
     
    file  netloc.h [code]
     
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/projects/hwloc/doc/v2.9.2/dudley.png b/projects/hwloc/doc/v2.9.2/dudley.png deleted file mode 100644 index a1df53f98..000000000 Binary files a/projects/hwloc/doc/v2.9.2/dudley.png and /dev/null differ diff --git a/projects/hwloc/doc/v2.9.2/dynsections.js b/projects/hwloc/doc/v2.9.2/dynsections.js deleted file mode 100644 index 3174bd7be..000000000 --- a/projects/hwloc/doc/v2.9.2/dynsections.js +++ /dev/null @@ -1,121 +0,0 @@ -/* - @licstart The following is the entire license notice for the JavaScript code in this file. - - The MIT License (MIT) - - Copyright (C) 1997-2020 by Dimitri van Heesch - - Permission is hereby granted, free of charge, to any person obtaining a copy of this software - and associated documentation files (the "Software"), to deal in the Software without restriction, - including without limitation the rights to use, copy, modify, merge, publish, distribute, - sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is - furnished to do so, subject to the following conditions: - - The above copyright notice and this permission notice shall be included in all copies or - substantial portions of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING - BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND - NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, - DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - - @licend The above is the entire license notice for the JavaScript code in this file - */ -function toggleVisibility(linkObj) -{ - var base = $(linkObj).attr('id'); - var summary = $('#'+base+'-summary'); - var content = $('#'+base+'-content'); - var trigger = $('#'+base+'-trigger'); - var src=$(trigger).attr('src'); - if (content.is(':visible')===true) { - content.hide(); - summary.show(); - $(linkObj).addClass('closed').removeClass('opened'); - $(trigger).attr('src',src.substring(0,src.length-8)+'closed.png'); - } else { - content.show(); - summary.hide(); - $(linkObj).removeClass('closed').addClass('opened'); - $(trigger).attr('src',src.substring(0,src.length-10)+'open.png'); - } - return false; -} - -function updateStripes() -{ - $('table.directory tr'). - removeClass('even').filter(':visible:even').addClass('even'); -} - -function toggleLevel(level) -{ - $('table.directory tr').each(function() { - var l = this.id.split('_').length-1; - var i = $('#img'+this.id.substring(3)); - var a = $('#arr'+this.id.substring(3)); - if (l - - - - - - -
    -
    Here is a list of all struct and union fields with links to the structures/unions they belong to:
    - -

    - a -

    - - -

    - b -

    - - -

    - c -

    - - -

    - d -

    - - -

    - e -

    - - -

    - f -

    - - -

    - g -

    - - -

    - i -

    - - -

    - k -

    - - -

    - l -

    - - -

    - m -

    - - -

    - n -

    - - -

    - o -

    - - -

    - p -

    - - -

    - r -

    - - -

    - s -

    - - -

    - t -

    - - -

    - u -

    - - -

    - v -

    -
    - - - - - - - -
    -  - -

    - a -

    - - -

    - b -

    - - -

    - c -

    - - -

    - d -

    - - -

    - e -

    - - -

    - f -

    - - -

    - g -

    - - -

    - i -

    - - -

    - k -

    - - -

    - l -

    - - -

    - m -

    - - -

    - n -

    - - -

    - o -

    - - -

    - p -

    - - -

    - r -

    - - -

    - s -

    - - -

    - t -

    - - -

    - u -

    - - -

    - v -

    -
    - - - - - - - -
    -
    Hardware Locality
    -
    -
    -

    Portable abstraction of parallel architectures for high-performance computing

    -
    -

    -

    -

    -

    -Introduction

    -

    The Hardware Locality (hwloc) software project aims at easing the process of discovering hardware resources in parallel architectures. It offers command-line tools and a C API for consulting these resources, their locality, attributes, and interconnection. hwloc primarily aims at helping high-performance computing (HPC) applications, but is also applicable to any project seeking to exploit code and/or data locality on modern computing platforms.

    -

    hwloc is actually made of two subprojects distributed together:

    -

    -See also the Related pages tab above for links to other sections. -

    -

    Netloc may be disabled, but the original hwloc cannot. Both hwloc and netloc APIs are documented after these sections.

    -

    -

    -

    -

    -Installation

    -

    hwloc (https://www.open-mpi.org/projects/hwloc/) is available under the BSD license. It is hosted as a sub-project of the overall Open MPI project (https://www.open-mpi.org/). Note that hwloc does not require any functionality from Open MPI – it is a wholly separate (and much smaller!) project and code base. It just happens to be hosted as part of the overall Open MPI project.

    -

    -Basic Installation

    -

    Installation is the fairly common GNU-based process:

    -
    shell$ ./configure --prefix=...
-shell$ make
-shell$ make install
-

    hwloc- and netloc-specific configure options and requirements are documented in sections hwloc Installation and Netloc Installation respectively.

    -

    Also note that if you install supplemental libraries in non-standard locations, hwloc's configure script may not be able to find them without some help. You may need to specify additional CPPFLAGS, LDFLAGS, or PKG_CONFIG_PATH values on the configure command line.

    -

    For example, if libpciaccess was installed into /opt/pciaccess, hwloc's configure script may not find it by default. Try adding PKG_CONFIG_PATH to the ./configure command line, like this:

    -
    ./configure PKG_CONFIG_PATH=/opt/pciaccess/lib/pkgconfig ...
-

    Running the "lstopo" tool is a good way to check as a graphical output whether hwloc properly detected the architecture of your node. Netloc command-line tools can be used to display the network topology interconnecting your nodes.

    -

    -Installing from a Git clone

    -

    Additionally, the code can be directly cloned from Git:

    -
    shell$ git clone https://github.com/open-mpi/hwloc.git
-shell$ cd hwloc
-shell$ ./autogen.sh
-

    Note that GNU Autoconf >=2.63, Automake >=1.11 and Libtool >=2.2.6 are required when building from a Git clone.

    -

    Nightly development snapshots are available on the web site, they can be configured and built without any need for Git or GNU Autotools.

    -

    -

    -

    -

    -Questions and Bugs

    -

    Bugs should be reported in the tracker (https://github.com/open-mpi/hwloc/issues). Opening a new issue automatically displays lots of hints about how to debug and report issues.

    -

    Questions may be sent to the users or developers mailing lists (https://www.open-mpi.org/community/lists/hwloc.php).

    -

    There is also a #hwloc IRC channel on Libera Chat (irc.libera.chat).

    -
    -
    -'; - for (var i in data.children) { - var url; - var link; - link = data.children[i].url; - if (link.substring(0,1)=='^') { - url = link.substring(1); - } else { - url = relPath+link; - } - result+='
  • '+ - data.children[i].text+''+ - makeTree(data.children[i],relPath)+'
    • '; - } - result+=''; - } - return result; - } - var searchBox; - if (searchEnabled) { - if (serverSide) { - searchBox='
    '+ - '
    '+ - '
    '+ - ''+ - '
    '+ - '
    '+ - '
    '+ - '
    '; - } else { - searchBox='
    '+ - ''+ - ''+ - ''+ - ''+ - ''+ - '' - '' - '
    '; - } - } - - $('#main-nav').before('
    '+ - ''+ - ''+ - '
    '); - $('#main-nav').append(makeTree(menudata,relPath)); - $('#main-nav').children(':first').addClass('sm sm-dox').attr('id','main-menu'); - if (searchBox) { - $('#main-menu').append('
  • '); - } - var $mainMenuState = $('#main-menu-state'); - var prevWidth = 0; - if ($mainMenuState.length) { - function initResizableIfExists() { - if (typeof initResizable==='function') initResizable(); - } - // animate mobile menu - $mainMenuState.change(function(e) { - var $menu = $('#main-menu'); - var options = { duration: 250, step: initResizableIfExists }; - if (this.checked) { - options['complete'] = function() { $menu.css('display', 'block') }; - $menu.hide().slideDown(options); - } else { - options['complete'] = function() { $menu.css('display', 'none') }; - $menu.show().slideUp(options); - } - }); - // set default menu visibility - function resetState() { - var $menu = $('#main-menu'); - var $mainMenuState = $('#main-menu-state'); - var newWidth = $(window).outerWidth(); - if (newWidth!=prevWidth) { - if ($(window).outerWidth()<768) { - $mainMenuState.prop('checked',false); $menu.hide(); - $('#searchBoxPos1').html(searchBox); - $('#searchBoxPos2').hide(); - } else { - $menu.show(); - $('#searchBoxPos1').empty(); - $('#searchBoxPos2').html(searchBox); - $('#searchBoxPos2').show(); - } - prevWidth = newWidth; - } - } - $(window).ready(function() { resetState(); initResizableIfExists(); }); - $(window).resize(resetState); - } - $('#main-menu').smartmenus(); -} -/* @license-end */ diff --git a/projects/hwloc/doc/v2.9.2/menudata.js b/projects/hwloc/doc/v2.9.2/menudata.js deleted file mode 100644 index 7dc9262eb..000000000 --- a/projects/hwloc/doc/v2.9.2/menudata.js +++ /dev/null @@ -1,71 +0,0 @@ -/* - @licstart The following is the entire license notice for the JavaScript code in this file. - - The MIT License (MIT) - - Copyright (C) 1997-2020 by Dimitri van Heesch - - Permission is hereby granted, free of charge, to any person obtaining a copy of this software - and associated documentation files (the "Software"), to deal in the Software without restriction, - including without limitation the rights to use, copy, modify, merge, publish, distribute, - sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is - furnished to do so, subject to the following conditions: - - The above copyright notice and this permission notice shall be included in all copies or - substantial portions of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING - BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND - NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, - DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - - @licend The above is the entire license notice for the JavaScript code in this file -*/ -var menudata={children:[ -{text:"Main Page",url:"index.php"}, -{text:"Related Pages",url:"pages.php"}, -{text:"Modules",url:"modules.php"}, -{text:"Data Structures",url:"annotated.php",children:[ -{text:"Data Structures",url:"annotated.php"}, -{text:"Data Fields",url:"functions.php",children:[ -{text:"All",url:"functions.php",children:[ -{text:"a",url:"functions.php#index_a"}, -{text:"b",url:"functions.php#index_b"}, -{text:"c",url:"functions.php#index_c"}, -{text:"d",url:"functions.php#index_d"}, -{text:"e",url:"functions.php#index_e"}, -{text:"f",url:"functions.php#index_f"}, -{text:"g",url:"functions.php#index_g"}, -{text:"i",url:"functions.php#index_i"}, -{text:"k",url:"functions.php#index_k"}, -{text:"l",url:"functions.php#index_l"}, -{text:"m",url:"functions.php#index_m"}, -{text:"n",url:"functions.php#index_n"}, -{text:"o",url:"functions.php#index_o"}, -{text:"p",url:"functions.php#index_p"}, -{text:"r",url:"functions.php#index_r"}, -{text:"s",url:"functions.php#index_s"}, -{text:"t",url:"functions.php#index_t"}, -{text:"u",url:"functions.php#index_u"}, -{text:"v",url:"functions.php#index_v"}]}, -{text:"Variables",url:"functions_vars.php",children:[ -{text:"a",url:"functions_vars.php#index_a"}, -{text:"b",url:"functions_vars.php#index_b"}, -{text:"c",url:"functions_vars.php#index_c"}, -{text:"d",url:"functions_vars.php#index_d"}, -{text:"e",url:"functions_vars.php#index_e"}, -{text:"f",url:"functions_vars.php#index_f"}, -{text:"g",url:"functions_vars.php#index_g"}, -{text:"i",url:"functions_vars.php#index_i"}, -{text:"k",url:"functions_vars.php#index_k"}, -{text:"l",url:"functions_vars.php#index_l"}, -{text:"m",url:"functions_vars.php#index_m"}, -{text:"n",url:"functions_vars.php#index_n"}, -{text:"o",url:"functions_vars.php#index_o"}, -{text:"p",url:"functions_vars.php#index_p"}, -{text:"r",url:"functions_vars.php#index_r"}, -{text:"s",url:"functions_vars.php#index_s"}, -{text:"t",url:"functions_vars.php#index_t"}, -{text:"u",url:"functions_vars.php#index_u"}, -{text:"v",url:"functions_vars.php#index_v"}]}]}]}]} diff --git a/projects/hwloc/doc/v2.9.2/modules.php b/projects/hwloc/doc/v2.9.2/modules.php deleted file mode 100644 index 8a9c56276..000000000 --- a/projects/hwloc/doc/v2.9.2/modules.php +++ /dev/null @@ -1,93 +0,0 @@ - - - - - - -
    -
    -
    Modules
    -
    -
    -
    Here is a list of all modules:
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     Error reporting in the API
     API version
     Object Sets (hwloc_cpuset_t and hwloc_nodeset_t)
     Object Types
     Object Structure and Attributes
     Topology Creation and Destruction
     Object levels, depths and types
     Converting between Object Types and Attributes, and Strings
     Consulting and Adding Key-Value Info Attributes
     CPU binding
     Memory binding
     Changing the Source of Topology Discovery
     Topology Detection Configuration and Query
     Modifying a loaded Topology
     Finding Objects inside a CPU set
     Finding Objects covering at least CPU set
     Looking at Ancestor and Child Objects
     Kinds of object Type
     Looking at Cache Objects
     Finding objects, miscellaneous helpers
     Distributing items over a topology
     CPU and node sets of entire topologies
     Converting between CPU sets and node sets
     Finding I/O objects
     The bitmap API
     Exporting Topologies to XML
     Exporting Topologies to Synthetic
     Retrieve distances between objects
     Helpers for consulting distance matrices
     Add distances between objects
     Remove distances between objects
     Comparing memory node attributes for finding where to allocate on
     Managing memory attributes
     Kinds of CPU cores
     Linux-specific helpers
     Interoperability with Linux libnuma unsigned long masks
     Interoperability with Linux libnuma bitmask
     Windows-specific helpers
     Interoperability with glibc sched affinity
     Interoperability with OpenCL
     Interoperability with the CUDA Driver API
     Interoperability with the CUDA Runtime API
     Interoperability with the NVIDIA Management Library
     Interoperability with the ROCm SMI Management Library
     Interoperability with the oneAPI Level Zero interface.
     Interoperability with OpenGL displays
     Interoperability with OpenFabrics
     Topology differences
     Sharing topologies between processes
     Components and Plugins: Discovery components
     Components and Plugins: Discovery backends
     Components and Plugins: Generic components
     Components and Plugins: Core functions to be used by components
     Components and Plugins: Filtering objects
     Components and Plugins: helpers for PCI discovery
     Components and Plugins: finding PCI objects during other discoveries
     Netloc API
    -
    -
    - - - - - - - -
    -
    Related Pages
    -
    -
    -
    Here is a list of all related documentation pages:
    - - - - - - - - - - - - - - - - - - - - -
     Hardware Locality (hwloc) Introduction
     Terms and Definitions
     Command-Line Tools
     Environment Variables
     CPU and Memory Binding Overview
     I/O Devices
     Miscellaneous objects
     Object attributes
     Topology Attributes: Distances, Memory Attributes and CPU Kinds
     Importing and exporting topologies from/to XML files
     Synthetic topologies
     Interoperability With Other Software
     Thread Safety
     Components and plugins
     Embedding hwloc in Other Software
     Frequently Asked Questions (FAQ)
     Upgrading to the hwloc 2.0 API
     Network Locality (netloc)
     Netloc with Scotch
    -
    -
    -li>h1,.sm>li>h2,.sm>li>h3,.sm>li>h4,.sm>li>h5,.sm>li>h6{margin:0;padding:0}.sm ul{display:none}.sm li,.sm a{position:relative}.sm a{display:block}.sm a.disabled{cursor:not-allowed}.sm:after{content:"\00a0";display:block;height:0;font:0px/0 serif;clear:both;visibility:hidden;overflow:hidden}.sm,.sm *,.sm *:before,.sm *:after{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box}.main-menu-btn{position:relative;display:inline-block;width:36px;height:36px;text-indent:36px;margin-left:8px;white-space:nowrap;overflow:hidden;cursor:pointer;-webkit-tap-highlight-color:rgba(0,0,0,0)}.main-menu-btn-icon,.main-menu-btn-icon:before,.main-menu-btn-icon:after{position:absolute;top:50%;left:2px;height:2px;width:24px;background:#666;-webkit-transition:all 0.25s;transition:all 0.25s}.main-menu-btn-icon:before{content:'';top:-7px;left:0}.main-menu-btn-icon:after{content:'';top:7px;left:0}#main-menu-state:checked~.main-menu-btn .main-menu-btn-icon{height:0}#main-menu-state:checked~.main-menu-btn .main-menu-btn-icon:before{top:0;-webkit-transform:rotate(-45deg);transform:rotate(-45deg)}#main-menu-state:checked~.main-menu-btn .main-menu-btn-icon:after{top:0;-webkit-transform:rotate(45deg);transform:rotate(45deg)}#main-menu-state{position:absolute;width:1px;height:1px;margin:-1px;border:0;padding:0;overflow:hidden;clip:rect(1px, 1px, 1px, 1px)}#main-menu-state:not(:checked)~#main-menu{display:none}#main-menu-state:checked~#main-menu{display:block}@media (min-width: 768px){.main-menu-btn{position:absolute;top:-99999px}#main-menu-state:not(:checked)~#main-menu{display:block}}.sm-dox{background-image:url("tab_b.png")}.sm-dox a,.sm-dox a:focus,.sm-dox a:hover,.sm-dox a:active{padding:0px 12px;padding-right:43px;font-family:"Lucida Grande","Geneva","Helvetica",Arial,sans-serif;font-size:13px;font-weight:bold;line-height:36px;text-decoration:none;text-shadow:0px 1px 1px rgba(255,255,255,0.9);color:#283A5D;outline:none}.sm-dox a:hover{background-image:url("tab_a.png");background-repeat:repeat-x;color:#fff;text-shadow:0px 1px 1px #000}.sm-dox a.current{color:#D23600}.sm-dox a.disabled{color:#bbb}.sm-dox a span.sub-arrow{position:absolute;top:50%;margin-top:-14px;left:auto;right:3px;width:28px;height:28px;overflow:hidden;font:bold 12px/28px monospace !important;text-align:center;text-shadow:none;background:rgba(255,255,255,0.5);border-radius:5px}.sm-dox a span.sub-arrow:before{display:block;content:'+'}.sm-dox a.highlighted span.sub-arrow:before{display:block;content:'-'}.sm-dox>li:first-child>a,.sm-dox>li:first-child>:not(ul) a{border-radius:5px 5px 0 0}.sm-dox>li:last-child>a,.sm-dox>li:last-child>*:not(ul) a,.sm-dox>li:last-child>ul,.sm-dox>li:last-child>ul>li:last-child>a,.sm-dox>li:last-child>ul>li:last-child>*:not(ul) a,.sm-dox>li:last-child>ul>li:last-child>ul,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>a,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>*:not(ul) a,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>a,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>*:not(ul) a,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>ul,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>a,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>*:not(ul) a,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>ul{border-radius:0 0 5px 5px}.sm-dox>li:last-child>a.highlighted,.sm-dox>li:last-child>*:not(ul) a.highlighted,.sm-dox>li:last-child>ul>li:last-child>a.highlighted,.sm-dox>li:last-child>ul>li:last-child>*:not(ul) a.highlighted,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>a.highlighted,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>*:not(ul) a.highlighted,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>a.highlighted,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>*:not(ul) a.highlighted,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>a.highlighted,.sm-dox>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>ul>li:last-child>*:not(ul) a.highlighted{border-radius:0}.sm-dox ul{background:rgba(162,162,162,0.1)}.sm-dox ul a,.sm-dox ul a:focus,.sm-dox ul a:hover,.sm-dox ul a:active{font-size:12px;border-left:8px solid transparent;line-height:36px;text-shadow:none;background-color:white;background-image:none}.sm-dox ul a:hover{background-image:url("tab_a.png");background-repeat:repeat-x;color:#fff;text-shadow:0px 1px 1px #000}.sm-dox ul ul a,.sm-dox ul ul a:hover,.sm-dox ul ul a:focus,.sm-dox ul ul a:active{border-left:16px solid transparent}.sm-dox ul ul ul a,.sm-dox ul ul ul a:hover,.sm-dox ul ul ul a:focus,.sm-dox ul ul ul a:active{border-left:24px solid transparent}.sm-dox ul ul ul ul a,.sm-dox ul ul ul ul a:hover,.sm-dox ul ul ul ul a:focus,.sm-dox ul ul ul ul a:active{border-left:32px solid transparent}.sm-dox ul ul ul ul ul a,.sm-dox ul ul ul ul ul a:hover,.sm-dox ul ul ul ul ul a:focus,.sm-dox ul ul ul ul ul a:active{border-left:40px solid transparent}@media (min-width: 768px){.sm-dox ul{position:absolute;width:12em}.sm-dox li{float:left}.sm-dox.sm-rtl li{float:right}.sm-dox ul li,.sm-dox.sm-rtl ul li,.sm-dox.sm-vertical li{float:none}.sm-dox a{white-space:nowrap}.sm-dox ul a,.sm-dox.sm-vertical a{white-space:normal}.sm-dox .sm-nowrap>li>a,.sm-dox .sm-nowrap>li>:not(ul) a{white-space:nowrap}.sm-dox{padding:0 10px;background-image:url("tab_b.png");line-height:36px}.sm-dox a span.sub-arrow{top:50%;margin-top:-2px;right:12px;width:0;height:0;border-width:4px;border-style:solid dashed dashed dashed;border-color:#283A5D transparent transparent transparent;background:transparent;border-radius:0}.sm-dox a,.sm-dox a:focus,.sm-dox a:active,.sm-dox a:hover,.sm-dox a.highlighted{padding:0px 12px;background-image:url("tab_s.png");background-repeat:no-repeat;background-position:right;border-radius:0 !important}.sm-dox a:hover{background-image:url("tab_a.png");background-repeat:repeat-x;color:#fff;text-shadow:0px 1px 1px #000}.sm-dox a:hover span.sub-arrow{border-color:#fff transparent transparent transparent}.sm-dox a.has-submenu{padding-right:24px}.sm-dox li{border-top:0}.sm-dox>li>ul:before,.sm-dox>li>ul:after{content:'';position:absolute;top:-18px;left:30px;width:0;height:0;overflow:hidden;border-width:9px;border-style:dashed dashed solid dashed;border-color:transparent transparent #bbb transparent}.sm-dox>li>ul:after{top:-16px;left:31px;border-width:8px;border-color:transparent transparent #fff transparent}.sm-dox ul{border:1px solid #bbb;padding:5px 0;background:#fff;border-radius:5px !important;box-shadow:0 5px 9px rgba(0,0,0,0.2)}.sm-dox ul a span.sub-arrow{right:8px;top:50%;margin-top:-5px;border-width:5px;border-color:transparent transparent transparent #555;border-style:dashed dashed dashed solid}.sm-dox ul a,.sm-dox ul a:hover,.sm-dox ul a:focus,.sm-dox ul a:active,.sm-dox ul a.highlighted{color:#555;background-image:none;border:0 !important;color:#555;background-image:none}.sm-dox ul a:hover{background-image:url("tab_a.png");background-repeat:repeat-x;color:#fff;text-shadow:0px 1px 1px #000}.sm-dox ul a:hover span.sub-arrow{border-color:transparent transparent transparent #fff}.sm-dox span.scroll-up,.sm-dox span.scroll-down{position:absolute;display:none;visibility:hidden;overflow:hidden;background:#fff;height:36px}.sm-dox span.scroll-up:hover,.sm-dox span.scroll-down:hover{background:#eee}.sm-dox span.scroll-up:hover span.scroll-up-arrow,.sm-dox span.scroll-up:hover span.scroll-down-arrow{border-color:transparent transparent #D23600 transparent}.sm-dox span.scroll-down:hover span.scroll-down-arrow{border-color:#D23600 transparent transparent transparent}.sm-dox span.scroll-up-arrow,.sm-dox span.scroll-down-arrow{position:absolute;top:0;left:50%;margin-left:-6px;width:0;height:0;overflow:hidden;border-width:6px;border-style:dashed dashed solid dashed;border-color:transparent transparent #555 transparent}.sm-dox span.scroll-down-arrow{top:8px;border-style:solid dashed dashed dashed;border-color:#555 transparent transparent transparent}.sm-dox.sm-rtl a.has-submenu{padding-right:12px;padding-left:24px}.sm-dox.sm-rtl a span.sub-arrow{right:auto;left:12px}.sm-dox.sm-rtl.sm-vertical a.has-submenu{padding:10px 20px}.sm-dox.sm-rtl.sm-vertical a span.sub-arrow{right:auto;left:8px;border-style:dashed solid dashed dashed;border-color:transparent #555 transparent transparent}.sm-dox.sm-rtl>li>ul:before{left:auto;right:30px}.sm-dox.sm-rtl>li>ul:after{left:auto;right:31px}.sm-dox.sm-rtl ul a.has-submenu{padding:10px 20px !important}.sm-dox.sm-rtl ul a span.sub-arrow{right:auto;left:8px;border-style:dashed solid dashed dashed;border-color:transparent #555 transparent transparent}.sm-dox.sm-vertical{padding:10px 0;border-radius:5px}.sm-dox.sm-vertical a{padding:10px 20px}.sm-dox.sm-vertical a:hover,.sm-dox.sm-vertical a:focus,.sm-dox.sm-vertical a:active,.sm-dox.sm-vertical a.highlighted{background:#fff}.sm-dox.sm-vertical a.disabled{background-image:url("tab_b.png")}.sm-dox.sm-vertical a span.sub-arrow{right:8px;top:50%;margin-top:-5px;border-width:5px;border-style:dashed dashed dashed solid;border-color:transparent transparent transparent #555}.sm-dox.sm-vertical>li>ul:before,.sm-dox.sm-vertical>li>ul:after{display:none}.sm-dox.sm-vertical ul a{padding:10px 20px}.sm-dox.sm-vertical ul a:hover,.sm-dox.sm-vertical ul a:focus,.sm-dox.sm-vertical ul a:active,.sm-dox.sm-vertical ul a.highlighted{background:#eee}.sm-dox.sm-vertical ul a.disabled{background:#fff}} diff --git a/projects/hwloc/doc/v2.9.2/www.open-mpi.org-css.inc b/projects/hwloc/doc/v2.9.2/www.open-mpi.org-css.inc deleted file mode 100644 index 339ffeb0b..000000000 --- a/projects/hwloc/doc/v2.9.2/www.open-mpi.org-css.inc +++ /dev/null @@ -1,2 +0,0 @@ - - diff --git a/projects/hwloc/doc/v2.9.2/www.open-mpi.org-footer.inc b/projects/hwloc/doc/v2.9.2/www.open-mpi.org-footer.inc deleted file mode 100644 index 50e092203..000000000 --- a/projects/hwloc/doc/v2.9.2/www.open-mpi.org-footer.inc +++ /dev/null @@ -1,2 +0,0 @@ -