Open MPI logo

Portable Hardware Locality (hwloc) Documentation: v1.7

  |   Home   |   Support   |   FAQ   |  
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 0x00010700
78 
80  unsigned hwloc_get_api_version(void);
81 
83 #define HWLOC_COMPONENT_ABI 2
84 
93 struct hwloc_topology;
98 typedef struct hwloc_topology * hwloc_topology_t;
99 
133 
151 
166 typedef enum {
167  /* ***************************************************************
168  WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
169 
170  If new enum values are added here, you MUST also go update the
171  obj_type_order[] and obj_order_type[] arrays in src/topology.c.
172 
173  WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
174  *************************************************************** */
175 
247  /* ***************************************************************
248  WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
249 
250  If new enum values are added here, you MUST also go update the
251  obj_type_order[] and obj_order_type[] arrays in src/topology.c.
252 
253  WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
254  *************************************************************** */
256 
264 
270 
289 
308 
311 };
312 
321 union hwloc_obj_attr_u;
322 
325  hwloc_uint64_t total_memory;
326  hwloc_uint64_t local_memory;
329  unsigned page_types_len;
336  hwloc_uint64_t size;
337  hwloc_uint64_t count;
338  } * page_types;
339 };
340 
345 struct hwloc_obj {
346  /* physical information */
348  unsigned os_index;
349  char *name;
356  /* global position */
357  unsigned depth;
362  unsigned logical_index;
364  signed os_level;
366  /* cousins are all objects of the same type (and depth) across the entire topology */
370  /* children of the same parent are siblings, even if they may have different type and depth */
371  struct hwloc_obj *parent;
372  unsigned sibling_rank;
376  /* children array below this object */
377  unsigned arity;
378  struct hwloc_obj **children;
382  /* misc */
383  void *userdata;
388  /* cpusets and nodesets */
389  hwloc_cpuset_t cpuset;
402  hwloc_cpuset_t complete_cpuset;
413  hwloc_cpuset_t online_cpuset;
421  hwloc_cpuset_t allowed_cpuset;
432  hwloc_nodeset_t nodeset;
449  hwloc_nodeset_t complete_nodeset;
463  hwloc_nodeset_t allowed_nodeset;
477  unsigned distances_count;
478 
480  unsigned infos_count;
487 };
491 typedef struct hwloc_obj * hwloc_obj_t;
492 
497  hwloc_uint64_t size;
498  unsigned depth;
499  unsigned linesize;
503  } cache;
506  unsigned depth;
507  } group;
510  unsigned short domain;
511  unsigned char bus, dev, func;
512  unsigned short class_id;
514  unsigned char revision;
515  float linkspeed; /* in GB/s */
516  } pcidev;
519  union {
521  } upstream;
523  union {
524  struct {
525  unsigned short domain;
527  } pci;
528  } downstream;
530  unsigned depth;
531  } bridge;
535  } osdev;
536 };
537 
553  unsigned relative_depth;
555  unsigned nbobjs;
560  float *latency;
565  float latency_max;
566  float latency_base;
570 };
571 
574  char *name;
575  char *value;
576 };
577 
592  int hwloc_topology_init (hwloc_topology_t *topologyp);
593 
611  int hwloc_topology_load(hwloc_topology_t topology);
612 
617  void hwloc_topology_destroy (hwloc_topology_t topology);
618 
630  void hwloc_topology_check(hwloc_topology_t topology);
631 
666  int hwloc_topology_ignore_type(hwloc_topology_t topology, hwloc_obj_type_t type);
667 
676  int hwloc_topology_ignore_type_keep_structure(hwloc_topology_t topology, hwloc_obj_type_t type);
677 
685  int hwloc_topology_ignore_all_keep_structure(hwloc_topology_t topology);
686 
701 
721 
733 
742 
751 
759 };
760 
770  int hwloc_topology_set_flags (hwloc_topology_t topology, unsigned long flags);
771 
786  int hwloc_topology_set_pid(hwloc_topology_t restrict topology, hwloc_pid_t pid);
787 
814  int hwloc_topology_set_fsroot(hwloc_topology_t restrict topology, const char * restrict fsroot_path);
815 
843  int hwloc_topology_set_synthetic(hwloc_topology_t restrict topology, const char * restrict description);
844 
871  int hwloc_topology_set_xml(hwloc_topology_t restrict topology, const char * restrict xmlpath);
872 
899  int hwloc_topology_set_xmlbuffer(hwloc_topology_t restrict topology, const char * restrict buffer, int size);
900 
917  int hwloc_topology_set_custom(hwloc_topology_t topology);
918 
936  int hwloc_topology_set_distance_matrix(hwloc_topology_t restrict topology,
937  hwloc_obj_type_t type, unsigned nbobjs,
938  unsigned *os_index, float *distances);
939 
943  unsigned char pu;
944 };
945 
949  unsigned char set_thisproc_cpubind;
951  unsigned char get_thisproc_cpubind;
953  unsigned char set_proc_cpubind;
955  unsigned char get_proc_cpubind;
957  unsigned char set_thisthread_cpubind;
959  unsigned char get_thisthread_cpubind;
961  unsigned char set_thread_cpubind;
963  unsigned char get_thread_cpubind;
970 };
971 
975  unsigned char set_thisproc_membind;
977  unsigned char get_thisproc_membind;
979  unsigned char set_proc_membind;
981  unsigned char get_proc_membind;
983  unsigned char set_thisthread_membind;
985  unsigned char get_thisthread_membind;
987  unsigned char set_area_membind;
989  unsigned char get_area_membind;
991  unsigned char alloc_membind;
993  unsigned char firsttouch_membind;
995  unsigned char bind_membind;
997  unsigned char interleave_membind;
999  unsigned char replicate_membind;
1001  unsigned char nexttouch_membind;
1002 
1004  unsigned char migrate_membind;
1005 };
1006 
1017 };
1018 
1020  const struct hwloc_topology_support *hwloc_topology_get_support(hwloc_topology_t restrict topology);
1021 
1043  int hwloc_topology_export_xml(hwloc_topology_t topology, const char *xmlpath);
1044 
1061  int hwloc_topology_export_xmlbuffer(hwloc_topology_t topology, char **xmlbuffer, int *buflen);
1062 
1064  void hwloc_free_xmlbuffer(hwloc_topology_t topology, char *xmlbuffer);
1065 
1082  void hwloc_topology_set_userdata_export_callback(hwloc_topology_t topology,
1083  void (*export_cb)(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj));
1084 
1110  int hwloc_export_obj_userdata(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length);
1111 
1125  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);
1126 
1147  void hwloc_topology_set_userdata_import_callback(hwloc_topology_t topology,
1148  void (*import_cb)(hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length));
1149 
1172  hwloc_obj_t hwloc_topology_insert_misc_object_by_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, const char *name);
1173 
1189  hwloc_obj_t hwloc_topology_insert_misc_object_by_parent(hwloc_topology_t topology, hwloc_obj_t parent, const char *name);
1190 
1198 
1204 
1210 };
1211 
1233  int hwloc_topology_restrict(hwloc_topology_t restrict topology, hwloc_const_cpuset_t cpuset, unsigned long flags);
1234 
1252  unsigned hwloc_topology_get_depth(hwloc_topology_t restrict topology) ;
1253 
1276  int hwloc_get_type_depth (hwloc_topology_t topology, hwloc_obj_type_t type);
1277 
1284 };
1285 
1290  hwloc_obj_type_t hwloc_get_depth_type (hwloc_topology_t topology, unsigned depth) ;
1291 
1294  unsigned hwloc_get_nbobjs_by_depth (hwloc_topology_t topology, unsigned depth) ;
1295 
1301 static inline int
1302 hwloc_get_nbobjs_by_type (hwloc_topology_t topology, hwloc_obj_type_t type) ;
1303 static inline int
1304 hwloc_get_nbobjs_by_type (hwloc_topology_t topology, hwloc_obj_type_t type)
1305 {
1306  int depth = hwloc_get_type_depth(topology, type);
1307  if (depth == HWLOC_TYPE_DEPTH_UNKNOWN)
1308  return 0;
1309  if (depth == HWLOC_TYPE_DEPTH_MULTIPLE)
1310  return -1; /* FIXME: agregate nbobjs from different levels? */
1311  return hwloc_get_nbobjs_by_depth(topology, depth);
1312 }
1313 
1321  int hwloc_topology_is_thissystem(hwloc_topology_t restrict topology) ;
1322 
1329  unsigned long hwloc_topology_get_flags (hwloc_topology_t topology);
1330 
1345  hwloc_obj_t hwloc_get_obj_by_depth (hwloc_topology_t topology, unsigned depth, unsigned idx) ;
1346 
1353 static inline hwloc_obj_t
1354 hwloc_get_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx) ;
1355 static inline hwloc_obj_t
1356 hwloc_get_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx)
1357 {
1358  int depth = hwloc_get_type_depth(topology, type);
1359  if (depth == HWLOC_TYPE_DEPTH_UNKNOWN)
1360  return NULL;
1361  if (depth == HWLOC_TYPE_DEPTH_MULTIPLE)
1362  return NULL;
1363  return hwloc_get_obj_by_depth(topology, depth, idx);
1364 }
1365 
1375  const char * hwloc_obj_type_string (hwloc_obj_type_t type) ;
1376 
1381  hwloc_obj_type_t hwloc_obj_type_of_string (const char * string) ;
1382 
1393  int hwloc_obj_type_snprintf(char * restrict string, size_t size, hwloc_obj_t obj,
1394  int verbose);
1395 
1407  int hwloc_obj_attr_snprintf(char * restrict string, size_t size, hwloc_obj_t obj, const char * restrict separator,
1408  int verbose);
1409 
1430  int hwloc_obj_snprintf(char * restrict string, size_t size,
1431  hwloc_topology_t topology, hwloc_obj_t obj,
1432  const char * restrict indexprefix, int verbose);
1433 
1441  int hwloc_obj_cpuset_snprintf(char * restrict str, size_t size, size_t nobj, const hwloc_obj_t * restrict objs);
1442 
1449 static inline const char *
1450 hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name) ;
1451 static inline const char *
1452 hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name)
1453 {
1454  unsigned i;
1455  for(i=0; i<obj->infos_count; i++)
1456  if (!strcmp(obj->infos[i].name, name))
1457  return obj->infos[i].value;
1458  return NULL;
1459 }
1460 
1471  void hwloc_obj_add_info(hwloc_obj_t obj, const char *name, const char *value);
1472 
1530 typedef enum {
1534 
1538 
1563 
1581 
1587  int hwloc_set_cpubind(hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags);
1588 
1594  int hwloc_get_cpubind(hwloc_topology_t topology, hwloc_cpuset_t set, int flags);
1595 
1603  int hwloc_set_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_cpuset_t set, int flags);
1604 
1616  int hwloc_get_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags);
1617 
1618 #ifdef hwloc_thread_t
1619 
1626  int hwloc_set_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_const_cpuset_t set, int flags);
1627 #endif
1628 
1629 #ifdef hwloc_thread_t
1630 
1637  int hwloc_get_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_cpuset_t set, int flags);
1638 #endif
1639 
1653  int hwloc_get_last_cpu_location(hwloc_topology_t topology, hwloc_cpuset_t set, int flags);
1654 
1669  int hwloc_get_proc_last_cpu_location(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags);
1670 
1738 typedef enum {
1742 
1752 
1756 
1765 
1778 
1785 
1792 
1804 typedef enum {
1810 
1815 
1823 
1829 
1843 
1856  int hwloc_set_membind_nodeset(hwloc_topology_t topology, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags);
1857 
1871  int hwloc_set_membind(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags);
1872 
1913  int hwloc_get_membind_nodeset(hwloc_topology_t topology, hwloc_nodeset_t nodeset, hwloc_membind_policy_t * policy, int flags);
1914 
1960  int hwloc_get_membind(hwloc_topology_t topology, hwloc_cpuset_t cpuset, hwloc_membind_policy_t * policy, int flags);
1961 
1971  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);
1972 
1982  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);
1983 
2020  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);
2021 
2061  int hwloc_get_proc_membind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t cpuset, hwloc_membind_policy_t * policy, int flags);
2062 
2069  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);
2070 
2077  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);
2078 
2101  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);
2102 
2127  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);
2128 
2136  void *hwloc_alloc(hwloc_topology_t topology, size_t len);
2137 
2147  void *hwloc_alloc_membind_nodeset(hwloc_topology_t topology, size_t len, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags) ;
2148 
2158  void *hwloc_alloc_membind(hwloc_topology_t topology, size_t len, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags) ;
2159 
2163  int hwloc_free(hwloc_topology_t topology, void *addr, size_t len);
2164 
2195  int hwloc_custom_insert_topology(hwloc_topology_t newtopology, hwloc_obj_t newparent, hwloc_topology_t oldtopology, hwloc_obj_t oldroot);
2196 
2213  hwloc_obj_t hwloc_custom_insert_group_object_by_parent(hwloc_topology_t topology, hwloc_obj_t parent, int groupdepth);
2214 
2219 #ifdef __cplusplus
2220 } /* extern "C" */
2221 #endif
2222 
2223 
2224 /* high-level helpers */
2225 #include <hwloc/helper.h>
2226 
2227 
2228 #endif /* HWLOC_H */