Hardware Locality (hwloc) 1.5.1

- Main Page
- Related Pages
- Modules
- Data Structures

hwloc.h
1 /*
2 * Copyright © 2009 CNRS
3 * Copyright © 2009-2012 inria. All rights reserved.
4 * Copyright © 2009-2012 Université Bordeaux 1
5 * Copyright © 2009-2011 Cisco Systems, Inc. All rights reserved.
6 * See COPYING in top-level directory.
7 */
8
9 /*=====================================================================
10 * PLEASE GO READ THE DOCUMENTATION!
11 * ------------------------------------------------
12 * $tarball_directory/doc/doxygen-doc/
13 * or
14 * http://www.open-mpi.org/projects/hwloc/doc/
15 *=====================================================================
16 *
17 * FAIR WARNING: Do NOT expect to be able to figure out all the
18 * subtleties of hwloc by simply reading function prototypes and
19 * constant descrptions here in this file.
20 *
21 * Hwloc has wonderful documentation in both PDF and HTML formats for
22 * your reading pleasure. The formal documentation explains a LOT of
23 * hwloc-specific concepts, provides definitions, and discusses the
24 * "big picture" for many of the things that you'll find here in this
25 * header file.
26 *
27 * The PDF/HTML documentation was generated via Doxygen; much of what
28 * you'll see in there is also here in this file. BUT THERE IS A LOT
29 * THAT IS IN THE PDF/HTML THAT IS ***NOT*** IN hwloc.h!
30 *
31 * There are entire paragraph-length descriptions, discussions, and
32 * pretty prictures to explain subtle corner cases, provide concrete
33 * examples, etc.
34 *
35 * Please, go read the documentation. :-)
36 *
37 *=====================================================================*/
38
46 #ifndef HWLOC_H
47 #define HWLOC_H
48
49 #include <hwloc/autogen/config.h>
50 #include <sys/types.h>
51 #include <stdio.h>
52 #include <string.h>
53 #include <limits.h>
54
55 /*
56 * Symbol transforms
57 */
58 #include <hwloc/rename.h>
59
60 /*
61 * Bitmap definitions
62 */
63
64 #include <hwloc/bitmap.h>
65
66
67 #ifdef __cplusplus
68 extern "C" {
69 #endif
70
71
77 #define HWLOC_API_VERSION 0x00010500
78
80 unsigned hwloc_get_api_version(void);
81
90 struct hwloc_topology;
95 typedef struct hwloc_topology * hwloc_topology_t;
96
127 typedef hwloc_bitmap_t hwloc_cpuset_t;
129 typedef hwloc_const_bitmap_t hwloc_const_cpuset_t;
130
144 typedef hwloc_bitmap_t hwloc_nodeset_t;
147 typedef hwloc_const_bitmap_t hwloc_const_nodeset_t;
148
163 typedef enum {
164 /* ***************************************************************
165 WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
166
167 If new enum values are added here, you MUST also go update the
168 obj_type_order[] and obj_order_type[] arrays in src/topology.c.
169
170 WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
171 *************************************************************** */
172
173 HWLOC_OBJ_SYSTEM,
178 HWLOC_OBJ_MACHINE,
183 HWLOC_OBJ_NODE,
187 HWLOC_OBJ_SOCKET,
191 HWLOC_OBJ_CACHE,
194 HWLOC_OBJ_CORE,
198 HWLOC_OBJ_PU,
207 HWLOC_OBJ_GROUP,
219 HWLOC_OBJ_MISC,
224 HWLOC_OBJ_BRIDGE,
231 HWLOC_OBJ_PCI_DEVICE,
236 HWLOC_OBJ_OS_DEVICE,
242 HWLOC_OBJ_TYPE_MAX
244 /* ***************************************************************
245 WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
246
247 If new enum values are added here, you MUST also go update the
248 obj_type_order[] and obj_order_type[] arrays in src/topology.c.
249
250 WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
251 *************************************************************** */
252 } hwloc_obj_type_t;
253
255 typedef enum hwloc_obj_cache_type_e {
256 HWLOC_OBJ_CACHE_UNIFIED,
257 HWLOC_OBJ_CACHE_DATA,
258 HWLOC_OBJ_CACHE_INSTRUCTION
260 } hwloc_obj_cache_type_t;
261
263 typedef enum hwloc_obj_bridge_type_e {
264 HWLOC_OBJ_BRIDGE_HOST,
265 HWLOC_OBJ_BRIDGE_PCI
266 } hwloc_obj_bridge_type_t;
267
269 typedef enum hwloc_obj_osdev_type_e {
270 HWLOC_OBJ_OSDEV_BLOCK,
272 HWLOC_OBJ_OSDEV_GPU,
274 HWLOC_OBJ_OSDEV_NETWORK,
276 HWLOC_OBJ_OSDEV_OPENFABRICS,
278 HWLOC_OBJ_OSDEV_DMA
280 } hwloc_obj_osdev_type_t;
281
299 int hwloc_compare_types (hwloc_obj_type_t type1, hwloc_obj_type_t type2) ;
300
301 enum hwloc_compare_types_e {
302 HWLOC_TYPE_UNORDERED = INT_MAX
303 };
304
313 union hwloc_obj_attr_u;
314
316 struct hwloc_obj_memory_s {
317 hwloc_uint64_t total_memory;
318 hwloc_uint64_t local_memory;
320 unsigned page_types_len;
326 struct hwloc_obj_memory_page_type_s {
327 hwloc_uint64_t size;
328 hwloc_uint64_t count;
329 } * page_types;
330 };
331
336 struct hwloc_obj {
337 /* physical information */
338 hwloc_obj_type_t type;
339 unsigned os_index;
340 char *name;
342 struct hwloc_obj_memory_s memory;
344 union hwloc_obj_attr_u *attr;
347 /* global position */
348 unsigned depth;
353 unsigned logical_index;
355 signed os_level;
357 /* cousins are all objects of the same type (and depth) across the entire topology */
358 struct hwloc_obj *next_cousin;
359 struct hwloc_obj *prev_cousin;
361 /* children of the same parent are siblings, even if they may have different type and depth */
362 struct hwloc_obj *parent;
363 unsigned sibling_rank;
364 struct hwloc_obj *next_sibling;
365 struct hwloc_obj *prev_sibling;
367 /* children array below this object */
368 unsigned arity;
369 struct hwloc_obj **children;
370 struct hwloc_obj *first_child;
371 struct hwloc_obj *last_child;
373 /* misc */
374 void *userdata;
376 /* cpusets and nodesets */
377 hwloc_cpuset_t cpuset;
390 hwloc_cpuset_t complete_cpuset;
401 hwloc_cpuset_t online_cpuset;
409 hwloc_cpuset_t allowed_cpuset;
420 hwloc_nodeset_t nodeset;
437 hwloc_nodeset_t complete_nodeset;
451 hwloc_nodeset_t allowed_nodeset;
464 struct hwloc_distances_s **distances;
465 unsigned distances_count;
466
467 struct hwloc_obj_info_s *infos;
468 unsigned infos_count;
470 int symmetric_subtree;
473 };
477 typedef struct hwloc_obj * hwloc_obj_t;
478
480 union hwloc_obj_attr_u {
482 struct hwloc_cache_attr_s {
483 hwloc_uint64_t size;
484 unsigned depth;
485 unsigned linesize;
486 int associativity;
488 hwloc_obj_cache_type_t type;
489 } cache;
491 struct hwloc_group_attr_s {
492 unsigned depth;
493 } group;
495 struct hwloc_pcidev_attr_s {
496 unsigned short domain;
497 unsigned char bus, dev, func;
498 unsigned short class_id;
499 unsigned short vendor_id, device_id, subvendor_id, subdevice_id;
500 unsigned char revision;
501 float linkspeed; /* in GB/s */
502 } pcidev;
504 struct hwloc_bridge_attr_s {
505 union {
506 struct hwloc_pcidev_attr_s pci;
507 } upstream;
508 hwloc_obj_bridge_type_t upstream_type;
509 union {
510 struct {
511 unsigned short domain;
512 unsigned char secondary_bus, subordinate_bus;
513 } pci;
514 } downstream;
515 hwloc_obj_bridge_type_t downstream_type;
516 unsigned depth;
517 } bridge;
519 struct hwloc_osdev_attr_s {
520 hwloc_obj_osdev_type_t type;
521 } osdev;
522 };
523
538 struct hwloc_distances_s {
539 unsigned relative_depth;
541 unsigned nbobjs;
546 float *latency;
551 float latency_max;
552 float latency_base;
556 };
557
559 struct hwloc_obj_info_s {
560 char *name;
561 char *value;
562 };
563
578 int hwloc_topology_init (hwloc_topology_t *topologyp);
579
592 int hwloc_topology_load(hwloc_topology_t topology);
593
598 void hwloc_topology_destroy (hwloc_topology_t topology);
599
611 void hwloc_topology_check(hwloc_topology_t topology);
612
647 int hwloc_topology_ignore_type(hwloc_topology_t topology, hwloc_obj_type_t type);
648
657 int hwloc_topology_ignore_type_keep_structure(hwloc_topology_t topology, hwloc_obj_type_t type);
658
666 int hwloc_topology_ignore_all_keep_structure(hwloc_topology_t topology);
667
672 enum hwloc_topology_flags_e {
673 HWLOC_TOPOLOGY_FLAG_WHOLE_SYSTEM = (1<<0),
682 HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM = (1<<1),
711 HWLOC_TOPOLOGY_FLAG_IO_DEVICES = (1<<2),
712
719 HWLOC_TOPOLOGY_FLAG_IO_BRIDGES = (1<<3),
720
727 HWLOC_TOPOLOGY_FLAG_WHOLE_IO = (1<<4),
728
734 HWLOC_TOPOLOGY_FLAG_ICACHES = (1<<5)
735 };
736
744 int hwloc_topology_set_flags (hwloc_topology_t topology, unsigned long flags);
745
760 int hwloc_topology_set_pid(hwloc_topology_t restrict topology, hwloc_pid_t pid);
761
786 int hwloc_topology_set_fsroot(hwloc_topology_t restrict topology, const char * restrict fsroot_path);
787
812 int hwloc_topology_set_synthetic(hwloc_topology_t restrict topology, const char * restrict description);
813
835 int hwloc_topology_set_xml(hwloc_topology_t restrict topology, const char * restrict xmlpath);
836
858 int hwloc_topology_set_xmlbuffer(hwloc_topology_t restrict topology, const char * restrict buffer, int size);
859
869 int hwloc_topology_set_custom(hwloc_topology_t topology);
870
888 int hwloc_topology_set_distance_matrix(hwloc_topology_t restrict topology,
889 hwloc_obj_type_t type, unsigned nbobjs,
890 unsigned *os_index, float *distances);
891
893 struct hwloc_topology_discovery_support {
895 unsigned char pu;
896 };
897
899 struct hwloc_topology_cpubind_support {
901 unsigned char set_thisproc_cpubind;
903 unsigned char get_thisproc_cpubind;
905 unsigned char set_proc_cpubind;
907 unsigned char get_proc_cpubind;
909 unsigned char set_thisthread_cpubind;
911 unsigned char get_thisthread_cpubind;
913 unsigned char set_thread_cpubind;
915 unsigned char get_thread_cpubind;
917 unsigned char get_thisproc_last_cpu_location;
919 unsigned char get_proc_last_cpu_location;
921 unsigned char get_thisthread_last_cpu_location;
922 };
923
925 struct hwloc_topology_membind_support {
927 unsigned char set_thisproc_membind;
929 unsigned char get_thisproc_membind;
931 unsigned char set_proc_membind;
933 unsigned char get_proc_membind;
935 unsigned char set_thisthread_membind;
937 unsigned char get_thisthread_membind;
939 unsigned char set_area_membind;
941 unsigned char get_area_membind;
943 unsigned char alloc_membind;
945 unsigned char firsttouch_membind;
947 unsigned char bind_membind;
949 unsigned char interleave_membind;
951 unsigned char replicate_membind;
953 unsigned char nexttouch_membind;
954
956 unsigned char migrate_membind;
957 };
958
965 struct hwloc_topology_support {
966 struct hwloc_topology_discovery_support *discovery;
967 struct hwloc_topology_cpubind_support *cpubind;
968 struct hwloc_topology_membind_support *membind;
969 };
970
972 const struct hwloc_topology_support *hwloc_topology_get_support(hwloc_topology_t restrict topology);
973
992 int hwloc_topology_export_xml(hwloc_topology_t topology, const char *xmlpath);
993
1007 int hwloc_topology_export_xmlbuffer(hwloc_topology_t topology, char **xmlbuffer, int *buflen);
1008
1010 void hwloc_free_xmlbuffer(hwloc_topology_t topology, char *xmlbuffer);
1011
1026 hwloc_obj_t hwloc_topology_insert_misc_object_by_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, const char *name);
1027
1043 hwloc_obj_t hwloc_topology_insert_misc_object_by_parent(hwloc_topology_t topology, hwloc_obj_t parent, const char *name);
1044
1046 enum hwloc_restrict_flags_e {
1047 HWLOC_RESTRICT_FLAG_ADAPT_DISTANCES = (1<<0),
1052 HWLOC_RESTRICT_FLAG_ADAPT_MISC = (1<<1),
1057 HWLOC_RESTRICT_FLAG_ADAPT_IO = (1<<2)
1062 };
1063
1076 int hwloc_topology_restrict(hwloc_topology_t restrict topology, hwloc_const_cpuset_t cpuset, unsigned long flags);
1077
1095 unsigned hwloc_topology_get_depth(hwloc_topology_t restrict topology) ;
1096
1119 int hwloc_get_type_depth (hwloc_topology_t topology, hwloc_obj_type_t type);
1120
1121 enum hwloc_get_type_depth_e {
1122 HWLOC_TYPE_DEPTH_UNKNOWN = -1,
1123 HWLOC_TYPE_DEPTH_MULTIPLE = -2,
1124 HWLOC_TYPE_DEPTH_BRIDGE = -3,
1125 HWLOC_TYPE_DEPTH_PCI_DEVICE = -4,
1126 HWLOC_TYPE_DEPTH_OS_DEVICE = -5
1127 };
1128
1133 hwloc_obj_type_t hwloc_get_depth_type (hwloc_topology_t topology, unsigned depth) ;
1134
1137 unsigned hwloc_get_nbobjs_by_depth (hwloc_topology_t topology, unsigned depth) ;
1138
1144 static inline int
1145 hwloc_get_nbobjs_by_type (hwloc_topology_t topology, hwloc_obj_type_t type) ;
1146 static inline int
1147 hwloc_get_nbobjs_by_type (hwloc_topology_t topology, hwloc_obj_type_t type)
1148 {
1149 int depth = hwloc_get_type_depth(topology, type);
1150 if (depth == HWLOC_TYPE_DEPTH_UNKNOWN)
1151 return 0;
1152 if (depth == HWLOC_TYPE_DEPTH_MULTIPLE)
1153 return -1; /* FIXME: agregate nbobjs from different levels? */
1154 return hwloc_get_nbobjs_by_depth(topology, depth);
1155 }
1156
1164 int hwloc_topology_is_thissystem(hwloc_topology_t restrict topology) ;
1165
1180 hwloc_obj_t hwloc_get_obj_by_depth (hwloc_topology_t topology, unsigned depth, unsigned idx) ;
1181
1188 static inline hwloc_obj_t
1189 hwloc_get_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx) ;
1190 static inline hwloc_obj_t
1191 hwloc_get_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx)
1192 {
1193 int depth = hwloc_get_type_depth(topology, type);
1194 if (depth == HWLOC_TYPE_DEPTH_UNKNOWN)
1195 return NULL;
1196 if (depth == HWLOC_TYPE_DEPTH_MULTIPLE)
1197 return NULL;
1198 return hwloc_get_obj_by_depth(topology, depth, idx);
1199 }
1200
1210 const char * hwloc_obj_type_string (hwloc_obj_type_t type) ;
1211
1216 hwloc_obj_type_t hwloc_obj_type_of_string (const char * string) ;
1217
1228 int hwloc_obj_type_snprintf(char * restrict string, size_t size, hwloc_obj_t obj,
1229 int verbose);
1230
1242 int hwloc_obj_attr_snprintf(char * restrict string, size_t size, hwloc_obj_t obj, const char * restrict separator,
1243 int verbose);
1244
1265 int hwloc_obj_snprintf(char * restrict string, size_t size,
1266 hwloc_topology_t topology, hwloc_obj_t obj,
1267 const char * restrict indexprefix, int verbose);
1268
1276 int hwloc_obj_cpuset_snprintf(char * restrict str, size_t size, size_t nobj, const hwloc_obj_t * restrict objs);
1277
1284 static inline const char *
1285 hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name) ;
1286 static inline const char *
1287 hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name)
1288 {
1289 unsigned i;
1290 for(i=0; i<obj->infos_count; i++)
1291 if (!strcmp(obj->infos[i].name, name))
1292 return obj->infos[i].value;
1293 return NULL;
1294 }
1295
1306 void hwloc_obj_add_info(hwloc_obj_t obj, const char *name, const char *value);
1307
1365 typedef enum {
1366 HWLOC_CPUBIND_PROCESS = (1<<0),
1369 HWLOC_CPUBIND_THREAD = (1<<1),
1371 HWLOC_CPUBIND_STRICT = (1<<2),
1399 HWLOC_CPUBIND_NOMEMBIND = (1<<3)
1419 } hwloc_cpubind_flags_t;
1420
1426 int hwloc_set_cpubind(hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags);
1427
1433 int hwloc_get_cpubind(hwloc_topology_t topology, hwloc_cpuset_t set, int flags);
1434
1442 int hwloc_set_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_cpuset_t set, int flags);
1443
1455 int hwloc_get_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags);
1456
1457 #ifdef hwloc_thread_t
1458
1465 int hwloc_set_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_const_cpuset_t set, int flags);
1466 #endif
1467
1468 #ifdef hwloc_thread_t
1469
1476 int hwloc_get_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_cpuset_t set, int flags);
1477 #endif
1478
1492 int hwloc_get_last_cpu_location(hwloc_topology_t topology, hwloc_cpuset_t set, int flags);
1493
1508 int hwloc_get_proc_last_cpu_location(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags);
1509
1577 typedef enum {
1578 HWLOC_MEMBIND_DEFAULT = 0,
1580 HWLOC_MEMBIND_FIRSTTOUCH = 1,
1594 HWLOC_MEMBIND_BIND = 2,
1596 HWLOC_MEMBIND_INTERLEAVE = 3,
1611 HWLOC_MEMBIND_REPLICATE = 4,
1633 HWLOC_MEMBIND_NEXTTOUCH = 5,
1643 HWLOC_MEMBIND_MIXED = -1
1648 } hwloc_membind_policy_t;
1649
1661 typedef enum {
1662 HWLOC_MEMBIND_PROCESS = (1<<0),
1669 HWLOC_MEMBIND_THREAD = (1<<1),
1675 HWLOC_MEMBIND_STRICT = (1<<2),
1686 HWLOC_MEMBIND_MIGRATE = (1<<3),
1694 HWLOC_MEMBIND_NOCPUBIND = (1<<4)
1717 } hwloc_membind_flags_t;
1718
1731 int hwloc_set_membind_nodeset(hwloc_topology_t topology, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags);
1732
1746 int hwloc_set_membind(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags);
1747
1788 int hwloc_get_membind_nodeset(hwloc_topology_t topology, hwloc_nodeset_t nodeset, hwloc_membind_policy_t * policy, int flags);
1789
1835 int hwloc_get_membind(hwloc_topology_t topology, hwloc_cpuset_t cpuset, hwloc_membind_policy_t * policy, int flags);
1836
1846 int hwloc_set_proc_membind_nodeset(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags);
1847
1857 int hwloc_set_proc_membind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags);
1858
1895 int hwloc_get_proc_membind_nodeset(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_nodeset_t nodeset, hwloc_membind_policy_t * policy, int flags);
1896
1936 int hwloc_get_proc_membind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t cpuset, hwloc_membind_policy_t * policy, int flags);
1937
1944 int hwloc_set_area_membind_nodeset(hwloc_topology_t topology, const void *addr, size_t len, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags);
1945
1952 int hwloc_set_area_membind(hwloc_topology_t topology, const void *addr, size_t len, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags);
1953
1976 int hwloc_get_area_membind_nodeset(hwloc_topology_t topology, const void *addr, size_t len, hwloc_nodeset_t nodeset, hwloc_membind_policy_t * policy, int flags);
1977
2002 int hwloc_get_area_membind(hwloc_topology_t topology, const void *addr, size_t len, hwloc_cpuset_t cpuset, hwloc_membind_policy_t * policy, int flags);
2003
2011 void *hwloc_alloc(hwloc_topology_t topology, size_t len);
2012
2022 void *hwloc_alloc_membind_nodeset(hwloc_topology_t topology, size_t len, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags) ;
2023
2033 void *hwloc_alloc_membind(hwloc_topology_t topology, size_t len, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags) ;
2034
2038 int hwloc_free(hwloc_topology_t topology, void *addr, size_t len);
2039
2070 int hwloc_custom_insert_topology(hwloc_topology_t newtopology, hwloc_obj_t newparent, hwloc_topology_t oldtopology, hwloc_obj_t oldroot);
2071
2088 hwloc_obj_t hwloc_custom_insert_group_object_by_parent(hwloc_topology_t topology, hwloc_obj_t parent, int groupdepth);
2089
2094 #ifdef __cplusplus
2095 } /* extern "C" */
2096 #endif
2097
2098
2099 /* high-level helpers */
2100 #include <hwloc/helper.h>
2101
2102
2103 #endif /* HWLOC_H */