Open MPI logo

Portable Hardware Locality (hwloc) Documentation: v1.6.2

  |   Home   |   Support   |   FAQ   |  
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 
130 
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 
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  *************************************************************** */
253 
261 
267 
281 
300 
303 };
304 
313 union hwloc_obj_attr_u;
314 
317  hwloc_uint64_t total_memory;
318  hwloc_uint64_t local_memory;
320  unsigned page_types_len;
327  hwloc_uint64_t size;
328  hwloc_uint64_t count;
329  } * page_types;
330 };
331 
336 struct hwloc_obj {
337  /* physical information */
339  unsigned os_index;
340  char *name;
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 */
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;
367  /* children array below this object */
368  unsigned arity;
369  struct hwloc_obj **children;
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;
468  unsigned distances_count;
469 
471  unsigned infos_count;
478 };
482 typedef struct hwloc_obj * hwloc_obj_t;
483 
488  hwloc_uint64_t size;
489  unsigned depth;
490  unsigned linesize;
494  } cache;
497  unsigned depth;
498  } group;
501  unsigned short domain;
502  unsigned char bus, dev, func;
503  unsigned short class_id;
505  unsigned char revision;
506  float linkspeed; /* in GB/s */
507  } pcidev;
510  union {
512  } upstream;
514  union {
515  struct {
516  unsigned short domain;
518  } pci;
519  } downstream;
521  unsigned depth;
522  } bridge;
526  } osdev;
527 };
528 
544  unsigned relative_depth;
546  unsigned nbobjs;
551  float *latency;
556  float latency_max;
557  float latency_base;
561 };
562 
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 
722 
730 
738 
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 
927  unsigned char pu;
928 };
929 
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;
954 };
955 
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 
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 
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 
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 {
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 {
1788 
1800 typedef enum {
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 */