Hardware Locality (hwloc) 1.5

- 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
741 int hwloc_topology_set_flags (hwloc_topology_t topology, unsigned long flags);
742
757 int hwloc_topology_set_pid(hwloc_topology_t restrict topology, hwloc_pid_t pid);
758
783 int hwloc_topology_set_fsroot(hwloc_topology_t restrict topology, const char * restrict fsroot_path);
784
809 int hwloc_topology_set_synthetic(hwloc_topology_t restrict topology, const char * restrict description);
810
832 int hwloc_topology_set_xml(hwloc_topology_t restrict topology, const char * restrict xmlpath);
833
855 int hwloc_topology_set_xmlbuffer(hwloc_topology_t restrict topology, const char * restrict buffer, int size);
856
866 int hwloc_topology_set_custom(hwloc_topology_t topology);
867
885 int hwloc_topology_set_distance_matrix(hwloc_topology_t restrict topology,
886 hwloc_obj_type_t type, unsigned nbobjs,
887 unsigned *os_index, float *distances);
888
890 struct hwloc_topology_discovery_support {
892 unsigned char pu;
893 };
894
896 struct hwloc_topology_cpubind_support {
898 unsigned char set_thisproc_cpubind;
900 unsigned char get_thisproc_cpubind;
902 unsigned char set_proc_cpubind;
904 unsigned char get_proc_cpubind;
906 unsigned char set_thisthread_cpubind;
908 unsigned char get_thisthread_cpubind;
910 unsigned char set_thread_cpubind;
912 unsigned char get_thread_cpubind;
914 unsigned char get_thisproc_last_cpu_location;
916 unsigned char get_proc_last_cpu_location;
918 unsigned char get_thisthread_last_cpu_location;
919 };
920
922 struct hwloc_topology_membind_support {
924 unsigned char set_thisproc_membind;
926 unsigned char get_thisproc_membind;
928 unsigned char set_proc_membind;
930 unsigned char get_proc_membind;
932 unsigned char set_thisthread_membind;
934 unsigned char get_thisthread_membind;
936 unsigned char set_area_membind;
938 unsigned char get_area_membind;
940 unsigned char alloc_membind;
942 unsigned char firsttouch_membind;
944 unsigned char bind_membind;
946 unsigned char interleave_membind;
948 unsigned char replicate_membind;
950 unsigned char nexttouch_membind;
951
953 unsigned char migrate_membind;
954 };
955
962 struct hwloc_topology_support {
963 struct hwloc_topology_discovery_support *discovery;
964 struct hwloc_topology_cpubind_support *cpubind;
965 struct hwloc_topology_membind_support *membind;
966 };
967
969 const struct hwloc_topology_support *hwloc_topology_get_support(hwloc_topology_t restrict topology);
970
989 int hwloc_topology_export_xml(hwloc_topology_t topology, const char *xmlpath);
990
1004 int hwloc_topology_export_xmlbuffer(hwloc_topology_t topology, char **xmlbuffer, int *buflen);
1005
1007 void hwloc_free_xmlbuffer(hwloc_topology_t topology, char *xmlbuffer);
1008
1023 hwloc_obj_t hwloc_topology_insert_misc_object_by_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, const char *name);
1024
1040 hwloc_obj_t hwloc_topology_insert_misc_object_by_parent(hwloc_topology_t topology, hwloc_obj_t parent, const char *name);
1041
1043 enum hwloc_restrict_flags_e {
1044 HWLOC_RESTRICT_FLAG_ADAPT_DISTANCES = (1<<0),
1049 HWLOC_RESTRICT_FLAG_ADAPT_MISC = (1<<1),
1054 HWLOC_RESTRICT_FLAG_ADAPT_IO = (1<<2)
1059 };
1060
1073 int hwloc_topology_restrict(hwloc_topology_t restrict topology, hwloc_const_cpuset_t cpuset, unsigned long flags);
1074
1092 unsigned hwloc_topology_get_depth(hwloc_topology_t restrict topology) ;
1093
1116 int hwloc_get_type_depth (hwloc_topology_t topology, hwloc_obj_type_t type);
1117
1118 enum hwloc_get_type_depth_e {
1119 HWLOC_TYPE_DEPTH_UNKNOWN = -1,
1120 HWLOC_TYPE_DEPTH_MULTIPLE = -2,
1121 HWLOC_TYPE_DEPTH_BRIDGE = -3,
1122 HWLOC_TYPE_DEPTH_PCI_DEVICE = -4,
1123 HWLOC_TYPE_DEPTH_OS_DEVICE = -5
1124 };
1125
1130 hwloc_obj_type_t hwloc_get_depth_type (hwloc_topology_t topology, unsigned depth) ;
1131
1134 unsigned hwloc_get_nbobjs_by_depth (hwloc_topology_t topology, unsigned depth) ;
1135
1141 static inline int
1142 hwloc_get_nbobjs_by_type (hwloc_topology_t topology, hwloc_obj_type_t type) ;
1143 static inline int
1144 hwloc_get_nbobjs_by_type (hwloc_topology_t topology, hwloc_obj_type_t type)
1145 {
1146 int depth = hwloc_get_type_depth(topology, type);
1147 if (depth == HWLOC_TYPE_DEPTH_UNKNOWN)
1148 return 0;
1149 if (depth == HWLOC_TYPE_DEPTH_MULTIPLE)
1150 return -1; /* FIXME: agregate nbobjs from different levels? */
1151 return hwloc_get_nbobjs_by_depth(topology, depth);
1152 }
1153
1161 int hwloc_topology_is_thissystem(hwloc_topology_t restrict topology) ;
1162
1177 hwloc_obj_t hwloc_get_obj_by_depth (hwloc_topology_t topology, unsigned depth, unsigned idx) ;
1178
1185 static inline hwloc_obj_t
1186 hwloc_get_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx) ;
1187 static inline hwloc_obj_t
1188 hwloc_get_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx)
1189 {
1190 int depth = hwloc_get_type_depth(topology, type);
1191 if (depth == HWLOC_TYPE_DEPTH_UNKNOWN)
1192 return NULL;
1193 if (depth == HWLOC_TYPE_DEPTH_MULTIPLE)
1194 return NULL;
1195 return hwloc_get_obj_by_depth(topology, depth, idx);
1196 }
1197
1207 const char * hwloc_obj_type_string (hwloc_obj_type_t type) ;
1208
1213 hwloc_obj_type_t hwloc_obj_type_of_string (const char * string) ;
1214
1225 int hwloc_obj_type_snprintf(char * restrict string, size_t size, hwloc_obj_t obj,
1226 int verbose);
1227
1239 int hwloc_obj_attr_snprintf(char * restrict string, size_t size, hwloc_obj_t obj, const char * restrict separator,
1240 int verbose);
1241
1262 int hwloc_obj_snprintf(char * restrict string, size_t size,
1263 hwloc_topology_t topology, hwloc_obj_t obj,
1264 const char * restrict indexprefix, int verbose);
1265
1273 int hwloc_obj_cpuset_snprintf(char * restrict str, size_t size, size_t nobj, const hwloc_obj_t * restrict objs);
1274
1281 static inline const char *
1282 hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name) ;
1283 static inline const char *
1284 hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name)
1285 {
1286 unsigned i;
1287 for(i=0; i<obj->infos_count; i++)
1288 if (!strcmp(obj->infos[i].name, name))
1289 return obj->infos[i].value;
1290 return NULL;
1291 }
1292
1303 void hwloc_obj_add_info(hwloc_obj_t obj, const char *name, const char *value);
1304
1362 typedef enum {
1363 HWLOC_CPUBIND_PROCESS = (1<<0),
1366 HWLOC_CPUBIND_THREAD = (1<<1),
1368 HWLOC_CPUBIND_STRICT = (1<<2),
1396 HWLOC_CPUBIND_NOMEMBIND = (1<<3)
1416 } hwloc_cpubind_flags_t;
1417
1423 int hwloc_set_cpubind(hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags);
1424
1430 int hwloc_get_cpubind(hwloc_topology_t topology, hwloc_cpuset_t set, int flags);
1431
1439 int hwloc_set_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_cpuset_t set, int flags);
1440
1452 int hwloc_get_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags);
1453
1454 #ifdef hwloc_thread_t
1455
1462 int hwloc_set_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_const_cpuset_t set, int flags);
1463 #endif
1464
1465 #ifdef hwloc_thread_t
1466
1473 int hwloc_get_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_cpuset_t set, int flags);
1474 #endif
1475
1489 int hwloc_get_last_cpu_location(hwloc_topology_t topology, hwloc_cpuset_t set, int flags);
1490
1505 int hwloc_get_proc_last_cpu_location(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags);
1506
1574 typedef enum {
1575 HWLOC_MEMBIND_DEFAULT = 0,
1577 HWLOC_MEMBIND_FIRSTTOUCH = 1,
1591 HWLOC_MEMBIND_BIND = 2,
1593 HWLOC_MEMBIND_INTERLEAVE = 3,
1608 HWLOC_MEMBIND_REPLICATE = 4,
1630 HWLOC_MEMBIND_NEXTTOUCH = 5,
1640 HWLOC_MEMBIND_MIXED = -1
1645 } hwloc_membind_policy_t;
1646
1658 typedef enum {
1659 HWLOC_MEMBIND_PROCESS = (1<<0),
1666 HWLOC_MEMBIND_THREAD = (1<<1),
1672 HWLOC_MEMBIND_STRICT = (1<<2),
1683 HWLOC_MEMBIND_MIGRATE = (1<<3),
1691 HWLOC_MEMBIND_NOCPUBIND = (1<<4)
1714 } hwloc_membind_flags_t;
1715
1728 int hwloc_set_membind_nodeset(hwloc_topology_t topology, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags);
1729
1743 int hwloc_set_membind(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags);
1744
1785 int hwloc_get_membind_nodeset(hwloc_topology_t topology, hwloc_nodeset_t nodeset, hwloc_membind_policy_t * policy, int flags);
1786
1832 int hwloc_get_membind(hwloc_topology_t topology, hwloc_cpuset_t cpuset, hwloc_membind_policy_t * policy, int flags);
1833
1843 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);
1844
1854 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);
1855
1892 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);
1893
1933 int hwloc_get_proc_membind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t cpuset, hwloc_membind_policy_t * policy, int flags);
1934
1941 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);
1942
1949 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);
1950
1973 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);
1974
1999 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);
2000
2008 void *hwloc_alloc(hwloc_topology_t topology, size_t len);
2009
2019 void *hwloc_alloc_membind_nodeset(hwloc_topology_t topology, size_t len, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags) ;
2020
2030 void *hwloc_alloc_membind(hwloc_topology_t topology, size_t len, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags) ;
2031
2035 int hwloc_free(hwloc_topology_t topology, void *addr, size_t len);
2036
2067 int hwloc_custom_insert_topology(hwloc_topology_t newtopology, hwloc_obj_t newparent, hwloc_topology_t oldtopology, hwloc_obj_t oldroot);
2068
2085 hwloc_obj_t hwloc_custom_insert_group_object_by_parent(hwloc_topology_t topology, hwloc_obj_t parent, int groupdepth);
2086
2091 #ifdef __cplusplus
2092 } /* extern "C" */
2093 #endif
2094
2095
2096 /* high-level helpers */
2097 #include <hwloc/helper.h>
2098
2099
2100 #endif /* HWLOC_H */