Open MPI logo

Portable Hardware Locality (hwloc) Documentation: v1.4.3

  |   Home   |   Support   |   FAQ   |  
hwloc.h
1 /*
2  * Copyright © 2009 CNRS
3  * Copyright © 2009-2011 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  * https://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 0x00010400
79 
81  unsigned hwloc_get_api_version(void);
82 
91 struct hwloc_topology;
96 typedef struct hwloc_topology * hwloc_topology_t;
97 
131 
149 
164 typedef enum {
165  /* ***************************************************************
166  WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
167 
168  If new enum values are added here, you MUST also go update the
169  obj_type_order[] and obj_order_type[] arrays in src/topology.c.
170 
171  WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
172  *************************************************************** */
173 
245  /* ***************************************************************
246  WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
247 
248  If new enum values are added here, you MUST also go update the
249  obj_type_order[] and obj_order_type[] arrays in src/topology.c.
250 
251  WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
252  *************************************************************** */
254 
260 
274 
293 
296 };
297 
306 union hwloc_obj_attr_u;
307 
310  hwloc_uint64_t total_memory;
311  hwloc_uint64_t local_memory;
313  unsigned page_types_len;
320  hwloc_uint64_t size;
321  hwloc_uint64_t count;
322  } * page_types;
323 };
324 
329 struct hwloc_obj {
330  /* physical information */
332  unsigned os_index;
333  char *name;
340  /* global position */
341  unsigned depth;
346  unsigned logical_index;
348  signed os_level;
350  /* cousins are all objects of the same type (and depth) across the entire topology */
354  /* children of the same parent are siblings, even if they may have different type and depth */
355  struct hwloc_obj *parent;
356  unsigned sibling_rank;
360  /* children array below this object */
361  unsigned arity;
362  struct hwloc_obj **children;
366  /* misc */
367  void *userdata;
369  /* cpusets and nodesets */
370  hwloc_cpuset_t cpuset;
383  hwloc_cpuset_t complete_cpuset;
394  hwloc_cpuset_t online_cpuset;
402  hwloc_cpuset_t allowed_cpuset;
413  hwloc_nodeset_t nodeset;
430  hwloc_nodeset_t complete_nodeset;
444  hwloc_nodeset_t allowed_nodeset;
458  unsigned distances_count;
459 
461  unsigned infos_count;
466 };
470 typedef struct hwloc_obj * hwloc_obj_t;
471 
476  hwloc_uint64_t size;
477  unsigned depth;
478  unsigned linesize;
481  } cache;
484  unsigned depth;
485  } group;
488  unsigned short domain;
489  unsigned char bus, dev, func;
490  unsigned short class_id;
492  unsigned char revision;
493  float linkspeed; /* in GB/s */
494  } pcidev;
497  union {
499  } upstream;
501  union {
502  struct {
503  unsigned short domain;
505  } pci;
506  } downstream;
508  unsigned depth;
509  } bridge;
513  } osdev;
514 };
515 
531  unsigned relative_depth;
533  unsigned nbobjs;
538  float *latency;
543  float latency_max;
544  float latency_base;
548 };
549 
552  char *name;
553  char *value;
554 };
555 
570  int hwloc_topology_init (hwloc_topology_t *topologyp);
571 
584  int hwloc_topology_load(hwloc_topology_t topology);
585 
590  void hwloc_topology_destroy (hwloc_topology_t topology);
591 
603  void hwloc_topology_check(hwloc_topology_t topology);
604 
639  int hwloc_topology_ignore_type(hwloc_topology_t topology, hwloc_obj_type_t type);
640 
649  int hwloc_topology_ignore_type_keep_structure(hwloc_topology_t topology, hwloc_obj_type_t type);
650 
658  int hwloc_topology_ignore_all_keep_structure(hwloc_topology_t topology);
659 
704 
712 
720 };
721 
726  int hwloc_topology_set_flags (hwloc_topology_t topology, unsigned long flags);
727 
742  int hwloc_topology_set_pid(hwloc_topology_t restrict topology, hwloc_pid_t pid);
743 
768  int hwloc_topology_set_fsroot(hwloc_topology_t restrict topology, const char * restrict fsroot_path);
769 
794  int hwloc_topology_set_synthetic(hwloc_topology_t restrict topology, const char * restrict description);
795 
817  int hwloc_topology_set_xml(hwloc_topology_t restrict topology, const char * restrict xmlpath);
818 
840  int hwloc_topology_set_xmlbuffer(hwloc_topology_t restrict topology, const char * restrict buffer, int size);
841 
851  int hwloc_topology_set_custom(hwloc_topology_t topology);
852 
870  int hwloc_topology_set_distance_matrix(hwloc_topology_t restrict topology,
871  hwloc_obj_type_t type, unsigned nbobjs,
872  unsigned *os_index, float *distances);
873 
877  unsigned char pu;
878 };
879 
883  unsigned char set_thisproc_cpubind;
885  unsigned char get_thisproc_cpubind;
887  unsigned char set_proc_cpubind;
889  unsigned char get_proc_cpubind;
891  unsigned char set_thisthread_cpubind;
893  unsigned char get_thisthread_cpubind;
895  unsigned char set_thread_cpubind;
897  unsigned char get_thread_cpubind;
904 };
905 
909  unsigned char set_thisproc_membind;
911  unsigned char get_thisproc_membind;
913  unsigned char set_proc_membind;
915  unsigned char get_proc_membind;
917  unsigned char set_thisthread_membind;
919  unsigned char get_thisthread_membind;
921  unsigned char set_area_membind;
923  unsigned char get_area_membind;
925  unsigned char alloc_membind;
927  unsigned char firsttouch_membind;
929  unsigned char bind_membind;
931  unsigned char interleave_membind;
933  unsigned char replicate_membind;
935  unsigned char nexttouch_membind;
936 
938  unsigned char migrate_membind;
939 };
940 
951 };
952 
954  const struct hwloc_topology_support *hwloc_topology_get_support(hwloc_topology_t restrict topology);
955 
970  int hwloc_topology_export_xml(hwloc_topology_t topology, const char *xmlpath);
971 
981  int hwloc_topology_export_xmlbuffer(hwloc_topology_t topology, char **xmlbuffer, int *buflen);
982 
984  void hwloc_free_xmlbuffer(hwloc_topology_t topology, char *xmlbuffer);
985 
997  hwloc_obj_t hwloc_topology_insert_misc_object_by_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, const char *name);
998 
1011  hwloc_obj_t hwloc_topology_insert_misc_object_by_parent(hwloc_topology_t topology, hwloc_obj_t parent, const char *name);
1012 
1030 };
1031 
1044  int hwloc_topology_restrict(hwloc_topology_t restrict topology, hwloc_const_cpuset_t cpuset, unsigned long flags);
1045 
1063  unsigned hwloc_topology_get_depth(hwloc_topology_t restrict topology) ;
1064 
1084  int hwloc_get_type_depth (hwloc_topology_t topology, hwloc_obj_type_t type);
1085 
1092 };
1093 
1098  hwloc_obj_type_t hwloc_get_depth_type (hwloc_topology_t topology, unsigned depth) ;
1099 
1102  unsigned hwloc_get_nbobjs_by_depth (hwloc_topology_t topology, unsigned depth) ;
1103 
1109 static inline int
1110 hwloc_get_nbobjs_by_type (hwloc_topology_t topology, hwloc_obj_type_t type) ;
1111 static inline int
1112 hwloc_get_nbobjs_by_type (hwloc_topology_t topology, hwloc_obj_type_t type)
1113 {
1114  int depth = hwloc_get_type_depth(topology, type);
1115  if (depth == HWLOC_TYPE_DEPTH_UNKNOWN)
1116  return 0;
1117  if (depth == HWLOC_TYPE_DEPTH_MULTIPLE)
1118  return -1; /* FIXME: agregate nbobjs from different levels? */
1119  return hwloc_get_nbobjs_by_depth(topology, depth);
1120 }
1121 
1129  int hwloc_topology_is_thissystem(hwloc_topology_t restrict topology) ;
1130 
1145  hwloc_obj_t hwloc_get_obj_by_depth (hwloc_topology_t topology, unsigned depth, unsigned idx) ;
1146 
1153 static inline hwloc_obj_t
1154 hwloc_get_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx) ;
1155 static inline hwloc_obj_t
1156 hwloc_get_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx)
1157 {
1158  int depth = hwloc_get_type_depth(topology, type);
1159  if (depth == HWLOC_TYPE_DEPTH_UNKNOWN)
1160  return NULL;
1161  if (depth == HWLOC_TYPE_DEPTH_MULTIPLE)
1162  return NULL;
1163  return hwloc_get_obj_by_depth(topology, depth, idx);
1164 }
1165 
1175  const char * hwloc_obj_type_string (hwloc_obj_type_t type) ;
1176 
1181  hwloc_obj_type_t hwloc_obj_type_of_string (const char * string) ;
1182 
1193  int hwloc_obj_type_snprintf(char * restrict string, size_t size, hwloc_obj_t obj,
1194  int verbose);
1195 
1207  int hwloc_obj_attr_snprintf(char * restrict string, size_t size, hwloc_obj_t obj, const char * restrict separator,
1208  int verbose);
1209 
1230  int hwloc_obj_snprintf(char * restrict string, size_t size,
1231  hwloc_topology_t topology, hwloc_obj_t obj,
1232  const char * restrict indexprefix, int verbose);
1233 
1241  int hwloc_obj_cpuset_snprintf(char * restrict str, size_t size, size_t nobj, const hwloc_obj_t * restrict objs);
1242 
1249 static inline const char *
1250 hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name) ;
1251 static inline const char *
1252 hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name)
1253 {
1254  unsigned i;
1255  for(i=0; i<obj->infos_count; i++)
1256  if (!strcmp(obj->infos[i].name, name))
1257  return obj->infos[i].value;
1258  return NULL;
1259 }
1260 
1268  void hwloc_obj_add_info(hwloc_obj_t obj, const char *name, const char *value);
1269 
1327 typedef enum {
1382 
1388  int hwloc_set_cpubind(hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags);
1389 
1395  int hwloc_get_cpubind(hwloc_topology_t topology, hwloc_cpuset_t set, int flags);
1396 
1404  int hwloc_set_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_cpuset_t set, int flags);
1405 
1417  int hwloc_get_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags);
1418 
1419 #ifdef hwloc_thread_t
1420 
1427  int hwloc_set_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_const_cpuset_t set, int flags);
1428 #endif
1429 
1430 #ifdef hwloc_thread_t
1431 
1438  int hwloc_get_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_cpuset_t set, int flags);
1439 #endif
1440 
1448  int hwloc_get_last_cpu_location(hwloc_topology_t topology, hwloc_cpuset_t set, int flags);
1449 
1466  int hwloc_get_proc_last_cpu_location(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags);
1467 
1535 typedef enum {
1607 
1619 typedef enum {
1676 
1689  int hwloc_set_membind_nodeset(hwloc_topology_t topology, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags);
1690 
1704  int hwloc_set_membind(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags);
1705 
1746  int hwloc_get_membind_nodeset(hwloc_topology_t topology, hwloc_nodeset_t nodeset, hwloc_membind_policy_t * policy, int flags);
1747 
1793  int hwloc_get_membind(hwloc_topology_t topology, hwloc_cpuset_t cpuset, hwloc_membind_policy_t * policy, int flags);
1794 
1804  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);
1805 
1815  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);
1816 
1853  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);
1854 
1894  int hwloc_get_proc_membind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t cpuset, hwloc_membind_policy_t * policy, int flags);
1895 
1902  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);
1903 
1910  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);
1911 
1934  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);
1935 
1960  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);
1961 
1969  void *hwloc_alloc(hwloc_topology_t topology, size_t len);
1970 
1980  void *hwloc_alloc_membind_nodeset(hwloc_topology_t topology, size_t len, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags) ;
1981 
1991  void *hwloc_alloc_membind(hwloc_topology_t topology, size_t len, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags) ;
1992 
1996  int hwloc_free(hwloc_topology_t topology, void *addr, size_t len);
1997 
2028  int hwloc_custom_insert_topology(hwloc_topology_t newtopology, hwloc_obj_t newparent, hwloc_topology_t oldtopology, hwloc_obj_t oldroot);
2029 
2046  hwloc_obj_t hwloc_custom_insert_group_object_by_parent(hwloc_topology_t topology, hwloc_obj_t parent, int groupdepth);
2047 
2052 #ifdef __cplusplus
2053 } /* extern "C" */
2054 #endif
2055 
2056 
2057 /* high-level helpers */
2058 #include <hwloc/helper.h>
2059 
2060 
2061 #endif /* HWLOC_H */