Hardware Locality (hwloc) 1.6.2

- Main Page
- Related Pages
- Modules
- Data Structures

hwloc.h
1 /*
2 * Copyright © 2009 CNRS
3 * Copyright © 2009-2013 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 0x00010600
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;
379 /* cpusets and nodesets */
380 hwloc_cpuset_t cpuset;
393 hwloc_cpuset_t complete_cpuset;
404 hwloc_cpuset_t online_cpuset;
412 hwloc_cpuset_t allowed_cpuset;
423 hwloc_nodeset_t nodeset;
440 hwloc_nodeset_t complete_nodeset;
454 hwloc_nodeset_t allowed_nodeset;
467 struct hwloc_distances_s **distances;
468 unsigned distances_count;
469
470 struct hwloc_obj_info_s *infos;
471 unsigned infos_count;
473 int symmetric_subtree;
478 };
482 typedef struct hwloc_obj * hwloc_obj_t;
483
485 union hwloc_obj_attr_u {
487 struct hwloc_cache_attr_s {
488 hwloc_uint64_t size;
489 unsigned depth;
490 unsigned linesize;
491 int associativity;
493 hwloc_obj_cache_type_t type;
494 } cache;
496 struct hwloc_group_attr_s {
497 unsigned depth;
498 } group;
500 struct hwloc_pcidev_attr_s {
501 unsigned short domain;
502 unsigned char bus, dev, func;
503 unsigned short class_id;
504 unsigned short vendor_id, device_id, subvendor_id, subdevice_id;
505 unsigned char revision;
506 float linkspeed; /* in GB/s */
507 } pcidev;
509 struct hwloc_bridge_attr_s {
510 union {
511 struct hwloc_pcidev_attr_s pci;
512 } upstream;
513 hwloc_obj_bridge_type_t upstream_type;
514 union {
515 struct {
516 unsigned short domain;
517 unsigned char secondary_bus, subordinate_bus;
518 } pci;
519 } downstream;
520 hwloc_obj_bridge_type_t downstream_type;
521 unsigned depth;
522 } bridge;
524 struct hwloc_osdev_attr_s {
525 hwloc_obj_osdev_type_t type;
526 } osdev;
527 };
528
543 struct hwloc_distances_s {
544 unsigned relative_depth;
546 unsigned nbobjs;
551 float *latency;
556 float latency_max;
557 float latency_base;
561 };
562
564 struct hwloc_obj_info_s {
565 char *name;
566 char *value;
567 };
568
583 int hwloc_topology_init (hwloc_topology_t *topologyp);
584
602 int hwloc_topology_load(hwloc_topology_t topology);
603
608 void hwloc_topology_destroy (hwloc_topology_t topology);
609
621 void hwloc_topology_check(hwloc_topology_t topology);
622
657 int hwloc_topology_ignore_type(hwloc_topology_t topology, hwloc_obj_type_t type);
658
667 int hwloc_topology_ignore_type_keep_structure(hwloc_topology_t topology, hwloc_obj_type_t type);
668
676 int hwloc_topology_ignore_all_keep_structure(hwloc_topology_t topology);
677
682 enum hwloc_topology_flags_e {
683 HWLOC_TOPOLOGY_FLAG_WHOLE_SYSTEM = (1<<0),
692 HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM = (1<<1),
721 HWLOC_TOPOLOGY_FLAG_IO_DEVICES = (1<<2),
722
729 HWLOC_TOPOLOGY_FLAG_IO_BRIDGES = (1<<3),
730
737 HWLOC_TOPOLOGY_FLAG_WHOLE_IO = (1<<4),
738
744 HWLOC_TOPOLOGY_FLAG_ICACHES = (1<<5)
745 };
746
754 int hwloc_topology_set_flags (hwloc_topology_t topology, unsigned long flags);
755
770 int hwloc_topology_set_pid(hwloc_topology_t restrict topology, hwloc_pid_t pid);
771
798 int hwloc_topology_set_fsroot(hwloc_topology_t restrict topology, const char * restrict fsroot_path);
799
827 int hwloc_topology_set_synthetic(hwloc_topology_t restrict topology, const char * restrict description);
828
855 int hwloc_topology_set_xml(hwloc_topology_t restrict topology, const char * restrict xmlpath);
856
883 int hwloc_topology_set_xmlbuffer(hwloc_topology_t restrict topology, const char * restrict buffer, int size);
884
901 int hwloc_topology_set_custom(hwloc_topology_t topology);
902
920 int hwloc_topology_set_distance_matrix(hwloc_topology_t restrict topology,
921 hwloc_obj_type_t type, unsigned nbobjs,
922 unsigned *os_index, float *distances);
923
925 struct hwloc_topology_discovery_support {
927 unsigned char pu;
928 };
929
931 struct hwloc_topology_cpubind_support {
933 unsigned char set_thisproc_cpubind;
935 unsigned char get_thisproc_cpubind;
937 unsigned char set_proc_cpubind;
939 unsigned char get_proc_cpubind;
941 unsigned char set_thisthread_cpubind;
943 unsigned char get_thisthread_cpubind;
945 unsigned char set_thread_cpubind;
947 unsigned char get_thread_cpubind;
949 unsigned char get_thisproc_last_cpu_location;
951 unsigned char get_proc_last_cpu_location;
953 unsigned char get_thisthread_last_cpu_location;
954 };
955
957 struct hwloc_topology_membind_support {
959 unsigned char set_thisproc_membind;
961 unsigned char get_thisproc_membind;
963 unsigned char set_proc_membind;
965 unsigned char get_proc_membind;
967 unsigned char set_thisthread_membind;
969 unsigned char get_thisthread_membind;
971 unsigned char set_area_membind;
973 unsigned char get_area_membind;
975 unsigned char alloc_membind;
977 unsigned char firsttouch_membind;
979 unsigned char bind_membind;
981 unsigned char interleave_membind;
983 unsigned char replicate_membind;
985 unsigned char nexttouch_membind;
986
988 unsigned char migrate_membind;
989 };
990
997 struct hwloc_topology_support {
998 struct hwloc_topology_discovery_support *discovery;
999 struct hwloc_topology_cpubind_support *cpubind;
1000 struct hwloc_topology_membind_support *membind;
1001 };
1002
1004 const struct hwloc_topology_support *hwloc_topology_get_support(hwloc_topology_t restrict topology);
1005
1027 int hwloc_topology_export_xml(hwloc_topology_t topology, const char *xmlpath);
1028
1045 int hwloc_topology_export_xmlbuffer(hwloc_topology_t topology, char **xmlbuffer, int *buflen);
1046
1048 void hwloc_free_xmlbuffer(hwloc_topology_t topology, char *xmlbuffer);
1049
1066 void hwloc_topology_set_userdata_export_callback(hwloc_topology_t topology,
1067 void (*export_cb)(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj));
1068
1094 int hwloc_export_obj_userdata(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length);
1095
1109 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);
1110
1131 void hwloc_topology_set_userdata_import_callback(hwloc_topology_t topology,
1132 void (*import_cb)(hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length));
1133
1156 hwloc_obj_t hwloc_topology_insert_misc_object_by_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, const char *name);
1157
1173 hwloc_obj_t hwloc_topology_insert_misc_object_by_parent(hwloc_topology_t topology, hwloc_obj_t parent, const char *name);
1174
1176 enum hwloc_restrict_flags_e {
1177 HWLOC_RESTRICT_FLAG_ADAPT_DISTANCES = (1<<0),
1182 HWLOC_RESTRICT_FLAG_ADAPT_MISC = (1<<1),
1187 HWLOC_RESTRICT_FLAG_ADAPT_IO = (1<<2)
1192 };
1193
1215 int hwloc_topology_restrict(hwloc_topology_t restrict topology, hwloc_const_cpuset_t cpuset, unsigned long flags);
1216
1234 unsigned hwloc_topology_get_depth(hwloc_topology_t restrict topology) ;
1235
1258 int hwloc_get_type_depth (hwloc_topology_t topology, hwloc_obj_type_t type);
1259
1260 enum hwloc_get_type_depth_e {
1261 HWLOC_TYPE_DEPTH_UNKNOWN = -1,
1262 HWLOC_TYPE_DEPTH_MULTIPLE = -2,
1263 HWLOC_TYPE_DEPTH_BRIDGE = -3,
1264 HWLOC_TYPE_DEPTH_PCI_DEVICE = -4,
1265 HWLOC_TYPE_DEPTH_OS_DEVICE = -5
1266 };
1267
1272 hwloc_obj_type_t hwloc_get_depth_type (hwloc_topology_t topology, unsigned depth) ;
1273
1276 unsigned hwloc_get_nbobjs_by_depth (hwloc_topology_t topology, unsigned depth) ;
1277
1283 static inline int
1284 hwloc_get_nbobjs_by_type (hwloc_topology_t topology, hwloc_obj_type_t type) ;
1285 static inline int
1286 hwloc_get_nbobjs_by_type (hwloc_topology_t topology, hwloc_obj_type_t type)
1287 {
1288 int depth = hwloc_get_type_depth(topology, type);
1289 if (depth == HWLOC_TYPE_DEPTH_UNKNOWN)
1290 return 0;
1291 if (depth == HWLOC_TYPE_DEPTH_MULTIPLE)
1292 return -1; /* FIXME: agregate nbobjs from different levels? */
1293 return hwloc_get_nbobjs_by_depth(topology, depth);
1294 }
1295
1303 int hwloc_topology_is_thissystem(hwloc_topology_t restrict topology) ;
1304
1319 hwloc_obj_t hwloc_get_obj_by_depth (hwloc_topology_t topology, unsigned depth, unsigned idx) ;
1320
1327 static inline hwloc_obj_t
1328 hwloc_get_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx) ;
1329 static inline hwloc_obj_t
1330 hwloc_get_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx)
1331 {
1332 int depth = hwloc_get_type_depth(topology, type);
1333 if (depth == HWLOC_TYPE_DEPTH_UNKNOWN)
1334 return NULL;
1335 if (depth == HWLOC_TYPE_DEPTH_MULTIPLE)
1336 return NULL;
1337 return hwloc_get_obj_by_depth(topology, depth, idx);
1338 }
1339
1349 const char * hwloc_obj_type_string (hwloc_obj_type_t type) ;
1350
1355 hwloc_obj_type_t hwloc_obj_type_of_string (const char * string) ;
1356
1367 int hwloc_obj_type_snprintf(char * restrict string, size_t size, hwloc_obj_t obj,
1368 int verbose);
1369
1381 int hwloc_obj_attr_snprintf(char * restrict string, size_t size, hwloc_obj_t obj, const char * restrict separator,
1382 int verbose);
1383
1404 int hwloc_obj_snprintf(char * restrict string, size_t size,
1405 hwloc_topology_t topology, hwloc_obj_t obj,
1406 const char * restrict indexprefix, int verbose);
1407
1415 int hwloc_obj_cpuset_snprintf(char * restrict str, size_t size, size_t nobj, const hwloc_obj_t * restrict objs);
1416
1423 static inline const char *
1424 hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name) ;
1425 static inline const char *
1426 hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name)
1427 {
1428 unsigned i;
1429 for(i=0; i<obj->infos_count; i++)
1430 if (!strcmp(obj->infos[i].name, name))
1431 return obj->infos[i].value;
1432 return NULL;
1433 }
1434
1445 void hwloc_obj_add_info(hwloc_obj_t obj, const char *name, const char *value);
1446
1504 typedef enum {
1505 HWLOC_CPUBIND_PROCESS = (1<<0),
1508 HWLOC_CPUBIND_THREAD = (1<<1),
1510 HWLOC_CPUBIND_STRICT = (1<<2),
1538 HWLOC_CPUBIND_NOMEMBIND = (1<<3)
1558 } hwloc_cpubind_flags_t;
1559
1565 int hwloc_set_cpubind(hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags);
1566
1572 int hwloc_get_cpubind(hwloc_topology_t topology, hwloc_cpuset_t set, int flags);
1573
1581 int hwloc_set_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_cpuset_t set, int flags);
1582
1594 int hwloc_get_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags);
1595
1596 #ifdef hwloc_thread_t
1597
1604 int hwloc_set_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_const_cpuset_t set, int flags);
1605 #endif
1606
1607 #ifdef hwloc_thread_t
1608
1615 int hwloc_get_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_cpuset_t set, int flags);
1616 #endif
1617
1631 int hwloc_get_last_cpu_location(hwloc_topology_t topology, hwloc_cpuset_t set, int flags);
1632
1647 int hwloc_get_proc_last_cpu_location(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags);
1648
1716 typedef enum {
1717 HWLOC_MEMBIND_DEFAULT = 0,
1719 HWLOC_MEMBIND_FIRSTTOUCH = 1,
1733 HWLOC_MEMBIND_BIND = 2,
1735 HWLOC_MEMBIND_INTERLEAVE = 3,
1750 HWLOC_MEMBIND_REPLICATE = 4,
1772 HWLOC_MEMBIND_NEXTTOUCH = 5,
1782 HWLOC_MEMBIND_MIXED = -1
1787 } hwloc_membind_policy_t;
1788
1800 typedef enum {
1801 HWLOC_MEMBIND_PROCESS = (1<<0),
1808 HWLOC_MEMBIND_THREAD = (1<<1),
1814 HWLOC_MEMBIND_STRICT = (1<<2),
1825 HWLOC_MEMBIND_MIGRATE = (1<<3),
1833 HWLOC_MEMBIND_NOCPUBIND = (1<<4)
1856 } hwloc_membind_flags_t;
1857
1870 int hwloc_set_membind_nodeset(hwloc_topology_t topology, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags);
1871
1885 int hwloc_set_membind(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags);
1886
1927 int hwloc_get_membind_nodeset(hwloc_topology_t topology, hwloc_nodeset_t nodeset, hwloc_membind_policy_t * policy, int flags);
1928
1974 int hwloc_get_membind(hwloc_topology_t topology, hwloc_cpuset_t cpuset, hwloc_membind_policy_t * policy, int flags);
1975
1985 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);
1986
1996 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);
1997
2034 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);
2035
2075 int hwloc_get_proc_membind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t cpuset, hwloc_membind_policy_t * policy, int flags);
2076
2083 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);
2084
2091 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);
2092
2115 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);
2116
2141 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);
2142
2150 void *hwloc_alloc(hwloc_topology_t topology, size_t len);
2151
2161 void *hwloc_alloc_membind_nodeset(hwloc_topology_t topology, size_t len, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags) ;
2162
2172 void *hwloc_alloc_membind(hwloc_topology_t topology, size_t len, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags) ;
2173
2177 int hwloc_free(hwloc_topology_t topology, void *addr, size_t len);
2178
2209 int hwloc_custom_insert_topology(hwloc_topology_t newtopology, hwloc_obj_t newparent, hwloc_topology_t oldtopology, hwloc_obj_t oldroot);
2210
2227 hwloc_obj_t hwloc_custom_insert_group_object_by_parent(hwloc_topology_t topology, hwloc_obj_t parent, int groupdepth);
2228
2233 #ifdef __cplusplus
2234 } /* extern "C" */
2235 #endif
2236
2237
2238 /* high-level helpers */
2239 #include <hwloc/helper.h>
2240
2241
2242 #endif /* HWLOC_H */