Open MPI logo

Portable Hardware Locality (hwloc) Documentation: v1.3.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 0x00010300
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;
342  unsigned logical_index;
344  signed os_level;
346  /* cousins are all objects of the same type (and depth) across the entire topology */
350  /* children of the same parent are siblings, even if they may have different type and depth */
351  struct hwloc_obj *parent;
352  unsigned sibling_rank;
356  /* children array below this object */
357  unsigned arity;
358  struct hwloc_obj **children;
362  /* misc */
363  void *userdata;
365  /* cpusets and nodesets */
366  hwloc_cpuset_t cpuset;
379  hwloc_cpuset_t complete_cpuset;
390  hwloc_cpuset_t online_cpuset;
398  hwloc_cpuset_t allowed_cpuset;
409  hwloc_nodeset_t nodeset;
426  hwloc_nodeset_t complete_nodeset;
440  hwloc_nodeset_t allowed_nodeset;
454  unsigned distances_count;
455 
457  unsigned infos_count;
458 };
462 typedef struct hwloc_obj * hwloc_obj_t;
463 
468  hwloc_uint64_t size;
469  unsigned depth;
470  unsigned linesize;
473  } cache;
476  unsigned depth;
477  } group;
480  unsigned short domain;
481  unsigned char bus, dev, func;
482  unsigned short class_id;
484  unsigned char revision;
485  float linkspeed; /* in GB/s */
486  } pcidev;
489  union {
491  } upstream;
493  union {
494  struct {
495  unsigned short domain;
497  } pci;
498  } downstream;
500  unsigned depth;
501  } bridge;
505  } osdev;
506 };
507 
523  unsigned relative_depth;
525  unsigned nbobjs;
530  float *latency;
535  float latency_max;
536  float latency_base;
540 };
541 
544  char *name;
545  char *value;
546 };
547 
562  int hwloc_topology_init (hwloc_topology_t *topologyp);
563 
576  int hwloc_topology_load(hwloc_topology_t topology);
577 
582  void hwloc_topology_destroy (hwloc_topology_t topology);
583 
595  void hwloc_topology_check(hwloc_topology_t topology);
596 
631  int hwloc_topology_ignore_type(hwloc_topology_t topology, hwloc_obj_type_t type);
632 
641  int hwloc_topology_ignore_type_keep_structure(hwloc_topology_t topology, hwloc_obj_type_t type);
642 
650  int hwloc_topology_ignore_all_keep_structure(hwloc_topology_t topology);
651 
686  /* \brief Detect PCI devices.
687  *
688  * By default, I/O devices are ignored. This flag enables I/O device
689  * detection using the libpci backend. Only the common PCI devices (GPUs,
690  * NICs, block devices, ...) and host bridges (objects that connect the host
691  * objects to an I/O subsystem) will be added to the topology.
692  * Uncommon devices and other bridges (such as PCI-to-PCI bridges) will be
693  * ignored.
694  */
696 
697  /* \brief Detect PCI bridges.
698  *
699  * This flag should be combined with HWLOC_TOPOLOGY_FLAG_IO_DEVICES to enable
700  * the detection of both common devices and of all useful bridges (bridges that
701  * have at least one device behind them).
702  */
704 
705  /* \brief Detect the whole PCI hierarchy.
706  *
707  * This flag enables detection of all I/O devices (even the uncommon ones)
708  * and bridges (even those that have no device behind them) using the libpci
709  * backend.
710  */
712 };
713 
718  int hwloc_topology_set_flags (hwloc_topology_t topology, unsigned long flags);
719 
738  int hwloc_topology_set_fsroot(hwloc_topology_t restrict topology, const char * restrict fsroot_path);
739 
754  int hwloc_topology_set_pid(hwloc_topology_t restrict topology, hwloc_pid_t pid);
755 
778  int hwloc_topology_set_synthetic(hwloc_topology_t restrict topology, const char * restrict description);
779 
796  int hwloc_topology_set_xml(hwloc_topology_t restrict topology, const char * restrict xmlpath);
797 
811  int hwloc_topology_set_xmlbuffer(hwloc_topology_t restrict topology, const char * restrict buffer, int size);
812 
828  int hwloc_topology_set_distance_matrix(hwloc_topology_t restrict topology,
829  hwloc_obj_type_t type, unsigned nbobjs,
830  unsigned *os_index, float *distances);
831 
835  unsigned char pu;
836 };
837 
841  unsigned char set_thisproc_cpubind;
843  unsigned char get_thisproc_cpubind;
845  unsigned char set_proc_cpubind;
847  unsigned char get_proc_cpubind;
849  unsigned char set_thisthread_cpubind;
851  unsigned char get_thisthread_cpubind;
853  unsigned char set_thread_cpubind;
855  unsigned char get_thread_cpubind;
862 };
863 
867  unsigned char set_thisproc_membind;
869  unsigned char get_thisproc_membind;
871  unsigned char set_proc_membind;
873  unsigned char get_proc_membind;
875  unsigned char set_thisthread_membind;
877  unsigned char get_thisthread_membind;
879  unsigned char set_area_membind;
881  unsigned char get_area_membind;
883  unsigned char alloc_membind;
885  unsigned char firsttouch_membind;
887  unsigned char bind_membind;
889  unsigned char interleave_membind;
891  unsigned char replicate_membind;
893  unsigned char nexttouch_membind;
894 
896  unsigned char migrate_membind;
897 };
898 
909 };
910 
912  const struct hwloc_topology_support *hwloc_topology_get_support(hwloc_topology_t restrict topology);
913 
928  int hwloc_topology_export_xml(hwloc_topology_t topology, const char *xmlpath);
929 
939  int hwloc_topology_export_xmlbuffer(hwloc_topology_t topology, char **xmlbuffer, int *buflen);
940 
942  void hwloc_free_xmlbuffer(hwloc_topology_t topology, char *xmlbuffer);
943 
955  hwloc_obj_t hwloc_topology_insert_misc_object_by_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, const char *name);
956 
969  hwloc_obj_t hwloc_topology_insert_misc_object_by_parent(hwloc_topology_t topology, hwloc_obj_t parent, const char *name);
970 
988 };
989 
1002  int hwloc_topology_restrict(hwloc_topology_t restrict topology, hwloc_const_cpuset_t cpuset, unsigned long flags);
1003 
1021  unsigned hwloc_topology_get_depth(hwloc_topology_t restrict topology) ;
1022 
1042  int hwloc_get_type_depth (hwloc_topology_t topology, hwloc_obj_type_t type);
1043 
1050 };
1051 
1056  hwloc_obj_type_t hwloc_get_depth_type (hwloc_topology_t topology, unsigned depth) ;
1057 
1060  unsigned hwloc_get_nbobjs_by_depth (hwloc_topology_t topology, unsigned depth) ;
1061 
1067 static inline int
1068 hwloc_get_nbobjs_by_type (hwloc_topology_t topology, hwloc_obj_type_t type) ;
1069 static inline int
1070 hwloc_get_nbobjs_by_type (hwloc_topology_t topology, hwloc_obj_type_t type)
1071 {
1072  int depth = hwloc_get_type_depth(topology, type);
1073  if (depth == HWLOC_TYPE_DEPTH_UNKNOWN)
1074  return 0;
1075  if (depth == HWLOC_TYPE_DEPTH_MULTIPLE)
1076  return -1; /* FIXME: agregate nbobjs from different levels? */
1077  return hwloc_get_nbobjs_by_depth(topology, depth);
1078 }
1079 
1087  int hwloc_topology_is_thissystem(hwloc_topology_t restrict topology) ;
1088 
1103  hwloc_obj_t hwloc_get_obj_by_depth (hwloc_topology_t topology, unsigned depth, unsigned idx) ;
1104 
1111 static inline hwloc_obj_t
1112 hwloc_get_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx) ;
1113 static inline hwloc_obj_t
1114 hwloc_get_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx)
1115 {
1116  int depth = hwloc_get_type_depth(topology, type);
1117  if (depth == HWLOC_TYPE_DEPTH_UNKNOWN)
1118  return NULL;
1119  if (depth == HWLOC_TYPE_DEPTH_MULTIPLE)
1120  return NULL;
1121  return hwloc_get_obj_by_depth(topology, depth, idx);
1122 }
1123 
1133  const char * hwloc_obj_type_string (hwloc_obj_type_t type) ;
1134 
1139  hwloc_obj_type_t hwloc_obj_type_of_string (const char * string) ;
1140 
1151  int hwloc_obj_type_snprintf(char * restrict string, size_t size, hwloc_obj_t obj,
1152  int verbose);
1153 
1165  int hwloc_obj_attr_snprintf(char * restrict string, size_t size, hwloc_obj_t obj, const char * restrict separator,
1166  int verbose);
1167 
1188  int hwloc_obj_snprintf(char * restrict string, size_t size,
1189  hwloc_topology_t topology, hwloc_obj_t obj,
1190  const char * restrict indexprefix, int verbose);
1191 
1199  int hwloc_obj_cpuset_snprintf(char * restrict str, size_t size, size_t nobj, const hwloc_obj_t * restrict objs);
1200 
1207 static inline const char *
1208 hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name) ;
1209 static inline const char *
1210 hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name)
1211 {
1212  unsigned i;
1213  for(i=0; i<obj->infos_count; i++)
1214  if (!strcmp(obj->infos[i].name, name))
1215  return obj->infos[i].value;
1216  return NULL;
1217 }
1218 
1226  void hwloc_obj_add_info(hwloc_obj_t obj, const char *name, const char *value);
1227 
1285 typedef enum {
1340 
1346  int hwloc_set_cpubind(hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags);
1347 
1353  int hwloc_get_cpubind(hwloc_topology_t topology, hwloc_cpuset_t set, int flags);
1354 
1362  int hwloc_set_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_cpuset_t set, int flags);
1363 
1375  int hwloc_get_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags);
1376 
1377 #ifdef hwloc_thread_t
1378 
1385  int hwloc_set_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_const_cpuset_t set, int flags);
1386 #endif
1387 
1388 #ifdef hwloc_thread_t
1389 
1396  int hwloc_get_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_cpuset_t set, int flags);
1397 #endif
1398 
1406  int hwloc_get_last_cpu_location(hwloc_topology_t topology, hwloc_cpuset_t set, int flags);
1407 
1424  int hwloc_get_proc_last_cpu_location(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags);
1425 
1485 typedef enum {
1554 
1566 typedef enum {
1623 
1636  int hwloc_set_membind_nodeset(hwloc_topology_t topology, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags);
1637 
1651  int hwloc_set_membind(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags);
1652 
1693  int hwloc_get_membind_nodeset(hwloc_topology_t topology, hwloc_nodeset_t nodeset, hwloc_membind_policy_t * policy, int flags);
1694 
1740  int hwloc_get_membind(hwloc_topology_t topology, hwloc_cpuset_t cpuset, hwloc_membind_policy_t * policy, int flags);
1741 
1751  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);
1752 
1762  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);
1763 
1800  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);
1801 
1841  int hwloc_get_proc_membind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t cpuset, hwloc_membind_policy_t * policy, int flags);
1842 
1849  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);
1850 
1857  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);
1858 
1881  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);
1882 
1907  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);
1908 
1916  void *hwloc_alloc(hwloc_topology_t topology, size_t len);
1917 
1927  void *hwloc_alloc_membind_nodeset(hwloc_topology_t topology, size_t len, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags) ;
1928 
1938  void *hwloc_alloc_membind(hwloc_topology_t topology, size_t len, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags) ;
1939 
1943  int hwloc_free(hwloc_topology_t topology, void *addr, size_t len);
1944 
1949 #ifdef __cplusplus
1950 } /* extern "C" */
1951 #endif
1952 
1953 
1954 /* high-level helpers */
1955 #include <hwloc/helper.h>
1956 
1957 
1958 #endif /* HWLOC_H */