Hardware Locality (hwloc)  1.7.1
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 #include <hwloc/cpuset.h>
66 
67 
68 #ifdef __cplusplus
69 extern "C" {
70 #endif
71 
72 
78 #define HWLOC_API_VERSION 0x00010700
79 
81  unsigned hwloc_get_api_version(void);
82 
84 #define HWLOC_COMPONENT_ABI 2
85 
94 struct hwloc_topology;
99 typedef struct hwloc_topology * hwloc_topology_t;
100 
134 
152 
167 typedef enum {
168  /* ***************************************************************
169  WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
170 
171  If new enum values are added here, you MUST also go update the
172  obj_type_order[] and obj_order_type[] arrays in src/topology.c.
173 
174  WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
175  *************************************************************** */
176 
248  /* ***************************************************************
249  WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
250 
251  If new enum values are added here, you MUST also go update the
252  obj_type_order[] and obj_order_type[] arrays in src/topology.c.
253 
254  WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
255  *************************************************************** */
257 
265 
271 
290 
309 
312 };
313 
322 union hwloc_obj_attr_u;
323 
326  hwloc_uint64_t total_memory;
327  hwloc_uint64_t local_memory;
330  unsigned page_types_len;
337  hwloc_uint64_t size;
338  hwloc_uint64_t count;
339  } * page_types;
340 };
341 
346 struct hwloc_obj {
347  /* physical information */
349  unsigned os_index;
350  char *name;
357  /* global position */
358  unsigned depth;
363  unsigned logical_index;
365  signed os_level;
367  /* cousins are all objects of the same type (and depth) across the entire topology */
371  /* children of the same parent are siblings, even if they may have different type and depth */
372  struct hwloc_obj *parent;
373  unsigned sibling_rank;
377  /* children array below this object */
378  unsigned arity;
379  struct hwloc_obj **children;
383  /* misc */
384  void *userdata;
389  /* cpusets and nodesets */
390  hwloc_cpuset_t cpuset;
403  hwloc_cpuset_t complete_cpuset;
414  hwloc_cpuset_t online_cpuset;
422  hwloc_cpuset_t allowed_cpuset;
433  hwloc_nodeset_t nodeset;
450  hwloc_nodeset_t complete_nodeset;
464  hwloc_nodeset_t allowed_nodeset;
478  unsigned distances_count;
479 
481  unsigned infos_count;
488 };
492 typedef struct hwloc_obj * hwloc_obj_t;
493 
498  hwloc_uint64_t size;
499  unsigned depth;
500  unsigned linesize;
504  } cache;
507  unsigned depth;
508  } group;
511  unsigned short domain;
512  unsigned char bus, dev, func;
513  unsigned short class_id;
515  unsigned char revision;
516  float linkspeed; /* in GB/s */
517  } pcidev;
520  union {
522  } upstream;
524  union {
525  struct {
526  unsigned short domain;
528  } pci;
529  } downstream;
531  unsigned depth;
532  } bridge;
536  } osdev;
537 };
538 
554  unsigned relative_depth;
556  unsigned nbobjs;
561  float *latency;
566  float latency_max;
567  float latency_base;
571 };
572 
575  char *name;
576  char *value;
577 };
578 
593  int hwloc_topology_init (hwloc_topology_t *topologyp);
594 
612  int hwloc_topology_load(hwloc_topology_t topology);
613 
618  void hwloc_topology_destroy (hwloc_topology_t topology);
619 
631  void hwloc_topology_check(hwloc_topology_t topology);
632 
667  int hwloc_topology_ignore_type(hwloc_topology_t topology, hwloc_obj_type_t type);
668 
677  int hwloc_topology_ignore_type_keep_structure(hwloc_topology_t topology, hwloc_obj_type_t type);
678 
686  int hwloc_topology_ignore_all_keep_structure(hwloc_topology_t topology);
687 
702 
722 
734 
743 
752 
760 };
761 
771  int hwloc_topology_set_flags (hwloc_topology_t topology, unsigned long flags);
772 
787  int hwloc_topology_set_pid(hwloc_topology_t restrict topology, hwloc_pid_t pid);
788 
815  int hwloc_topology_set_fsroot(hwloc_topology_t restrict topology, const char * restrict fsroot_path);
816 
844  int hwloc_topology_set_synthetic(hwloc_topology_t restrict topology, const char * restrict description);
845 
872  int hwloc_topology_set_xml(hwloc_topology_t restrict topology, const char * restrict xmlpath);
873 
900  int hwloc_topology_set_xmlbuffer(hwloc_topology_t restrict topology, const char * restrict buffer, int size);
901 
918  int hwloc_topology_set_custom(hwloc_topology_t topology);
919 
937  int hwloc_topology_set_distance_matrix(hwloc_topology_t restrict topology,
938  hwloc_obj_type_t type, unsigned nbobjs,
939  unsigned *os_index, float *distances);
940 
944  unsigned char pu;
945 };
946 
950  unsigned char set_thisproc_cpubind;
952  unsigned char get_thisproc_cpubind;
954  unsigned char set_proc_cpubind;
956  unsigned char get_proc_cpubind;
958  unsigned char set_thisthread_cpubind;
960  unsigned char get_thisthread_cpubind;
962  unsigned char set_thread_cpubind;
964  unsigned char get_thread_cpubind;
971 };
972 
976  unsigned char set_thisproc_membind;
978  unsigned char get_thisproc_membind;
980  unsigned char set_proc_membind;
982  unsigned char get_proc_membind;
984  unsigned char set_thisthread_membind;
986  unsigned char get_thisthread_membind;
988  unsigned char set_area_membind;
990  unsigned char get_area_membind;
992  unsigned char alloc_membind;
994  unsigned char firsttouch_membind;
996  unsigned char bind_membind;
998  unsigned char interleave_membind;
1000  unsigned char replicate_membind;
1002  unsigned char nexttouch_membind;
1003 
1005  unsigned char migrate_membind;
1006 };
1007 
1018 };
1019 
1021  const struct hwloc_topology_support *hwloc_topology_get_support(hwloc_topology_t restrict topology);
1022 
1044  int hwloc_topology_export_xml(hwloc_topology_t topology, const char *xmlpath);
1045 
1062  int hwloc_topology_export_xmlbuffer(hwloc_topology_t topology, char **xmlbuffer, int *buflen);
1063 
1065  void hwloc_free_xmlbuffer(hwloc_topology_t topology, char *xmlbuffer);
1066 
1083  void hwloc_topology_set_userdata_export_callback(hwloc_topology_t topology,
1084  void (*export_cb)(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj));
1085 
1111  int hwloc_export_obj_userdata(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length);
1112 
1126  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);
1127 
1148  void hwloc_topology_set_userdata_import_callback(hwloc_topology_t topology,
1149  void (*import_cb)(hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length));
1150 
1173  hwloc_obj_t hwloc_topology_insert_misc_object_by_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, const char *name);
1174 
1190  hwloc_obj_t hwloc_topology_insert_misc_object_by_parent(hwloc_topology_t topology, hwloc_obj_t parent, const char *name);
1191 
1199 
1205 
1211 };
1212 
1234  int hwloc_topology_restrict(hwloc_topology_t restrict topology, hwloc_const_cpuset_t cpuset, unsigned long flags);
1235 
1253  unsigned hwloc_topology_get_depth(hwloc_topology_t restrict topology) ;
1254 
1277  int hwloc_get_type_depth (hwloc_topology_t topology, hwloc_obj_type_t type);
1278 
1285 };
1286 
1291  hwloc_obj_type_t hwloc_get_depth_type (hwloc_topology_t topology, unsigned depth) ;
1292 
1295  unsigned hwloc_get_nbobjs_by_depth (hwloc_topology_t topology, unsigned depth) ;
1296 
1302 static inline int
1303 hwloc_get_nbobjs_by_type (hwloc_topology_t topology, hwloc_obj_type_t type) ;
1304 static inline int
1305 hwloc_get_nbobjs_by_type (hwloc_topology_t topology, hwloc_obj_type_t type)
1306 {
1307  int depth = hwloc_get_type_depth(topology, type);
1308  if (depth == HWLOC_TYPE_DEPTH_UNKNOWN)
1309  return 0;
1310  if (depth == HWLOC_TYPE_DEPTH_MULTIPLE)
1311  return -1; /* FIXME: agregate nbobjs from different levels? */
1312  return hwloc_get_nbobjs_by_depth(topology, depth);
1313 }
1314 
1322  int hwloc_topology_is_thissystem(hwloc_topology_t restrict topology) ;
1323 
1330  unsigned long hwloc_topology_get_flags (hwloc_topology_t topology);
1331 
1346  hwloc_obj_t hwloc_get_obj_by_depth (hwloc_topology_t topology, unsigned depth, unsigned idx) ;
1347 
1354 static inline hwloc_obj_t
1355 hwloc_get_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx) ;
1356 static inline hwloc_obj_t
1357 hwloc_get_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx)
1358 {
1359  int depth = hwloc_get_type_depth(topology, type);
1360  if (depth == HWLOC_TYPE_DEPTH_UNKNOWN)
1361  return NULL;
1362  if (depth == HWLOC_TYPE_DEPTH_MULTIPLE)
1363  return NULL;
1364  return hwloc_get_obj_by_depth(topology, depth, idx);
1365 }
1366 
1376  const char * hwloc_obj_type_string (hwloc_obj_type_t type) ;
1377 
1382  hwloc_obj_type_t hwloc_obj_type_of_string (const char * string) ;
1383 
1394  int hwloc_obj_type_snprintf(char * restrict string, size_t size, hwloc_obj_t obj,
1395  int verbose);
1396 
1408  int hwloc_obj_attr_snprintf(char * restrict string, size_t size, hwloc_obj_t obj, const char * restrict separator,
1409  int verbose);
1410 
1431  int hwloc_obj_snprintf(char * restrict string, size_t size,
1432  hwloc_topology_t topology, hwloc_obj_t obj,
1433  const char * restrict indexprefix, int verbose);
1434 
1442  int hwloc_obj_cpuset_snprintf(char * restrict str, size_t size, size_t nobj, const hwloc_obj_t * restrict objs);
1443 
1450 static inline const char *
1451 hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name) ;
1452 static inline const char *
1453 hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name)
1454 {
1455  unsigned i;
1456  for(i=0; i<obj->infos_count; i++)
1457  if (!strcmp(obj->infos[i].name, name))
1458  return obj->infos[i].value;
1459  return NULL;
1460 }
1461 
1472  void hwloc_obj_add_info(hwloc_obj_t obj, const char *name, const char *value);
1473 
1531 typedef enum {
1535 
1539 
1564 
1582 
1588  int hwloc_set_cpubind(hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags);
1589 
1595  int hwloc_get_cpubind(hwloc_topology_t topology, hwloc_cpuset_t set, int flags);
1596 
1604  int hwloc_set_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_cpuset_t set, int flags);
1605 
1617  int hwloc_get_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags);
1618 
1619 #ifdef hwloc_thread_t
1620 
1627  int hwloc_set_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_const_cpuset_t set, int flags);
1628 #endif
1629 
1630 #ifdef hwloc_thread_t
1631 
1638  int hwloc_get_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_cpuset_t set, int flags);
1639 #endif
1640 
1654  int hwloc_get_last_cpu_location(hwloc_topology_t topology, hwloc_cpuset_t set, int flags);
1655 
1670  int hwloc_get_proc_last_cpu_location(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags);
1671 
1739 typedef enum {
1743 
1753 
1757 
1766 
1779 
1786 
1793 
1805 typedef enum {
1811 
1816 
1824 
1830 
1844 
1857  int hwloc_set_membind_nodeset(hwloc_topology_t topology, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags);
1858 
1872  int hwloc_set_membind(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags);
1873 
1914  int hwloc_get_membind_nodeset(hwloc_topology_t topology, hwloc_nodeset_t nodeset, hwloc_membind_policy_t * policy, int flags);
1915 
1961  int hwloc_get_membind(hwloc_topology_t topology, hwloc_cpuset_t cpuset, hwloc_membind_policy_t * policy, int flags);
1962 
1972  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);
1973 
1983  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);
1984 
2021  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);
2022 
2062  int hwloc_get_proc_membind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t cpuset, hwloc_membind_policy_t * policy, int flags);
2063 
2070  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);
2071 
2078  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);
2079 
2102  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);
2103 
2128  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);
2129 
2137  void *hwloc_alloc(hwloc_topology_t topology, size_t len);
2138 
2148  void *hwloc_alloc_membind_nodeset(hwloc_topology_t topology, size_t len, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags) ;
2149 
2159  void *hwloc_alloc_membind(hwloc_topology_t topology, size_t len, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags) ;
2160 
2164  int hwloc_free(hwloc_topology_t topology, void *addr, size_t len);
2165 
2196  int hwloc_custom_insert_topology(hwloc_topology_t newtopology, hwloc_obj_t newparent, hwloc_topology_t oldtopology, hwloc_obj_t oldroot);
2197 
2214  hwloc_obj_t hwloc_custom_insert_group_object_by_parent(hwloc_topology_t topology, hwloc_obj_t parent, int groupdepth);
2215 
2220 #ifdef __cplusplus
2221 } /* extern "C" */
2222 #endif
2223 
2224 
2225 /* high-level helpers */
2226 #include <hwloc/helper.h>
2227 
2228 
2229 #endif /* HWLOC_H */