Hardware Locality (hwloc): hwloc.h Source File

Hardware Locality (hwloc) 1.2.2

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List

hwloc.h

    00001 /*
    00002  * Copyright © 2009 CNRS
    00003  * Copyright © 2009-2011 INRIA.  All rights reserved.
    00004  * Copyright © 2009-2011 Université Bordeaux 1
    00005  * Copyright © 2009-2011 Cisco Systems, Inc.  All rights reserved.
    00006  * See COPYING in top-level directory.
    00007  */
    00008
    00009 /*=====================================================================
    00010  *                 PLEASE GO READ THE DOCUMENTATION!
    00011  *         ------------------------------------------------
    00012  *               $tarball_directory/doc/doxygen-doc/
    00013  *                                or
    00014  *           http://www.open-mpi.org/projects/hwloc/doc/
    00015  *=====================================================================
    00016  *
    00017  * FAIR WARNING: Do NOT expect to be able to figure out all the
    00018  * subtleties of hwloc by simply reading function prototypes and
    00019  * constant descrptions here in this file.
    00020  *
    00021  * Hwloc has wonderful documentation in both PDF and HTML formats for
    00022  * your reading pleasure.  The formal documentation explains a LOT of
    00023  * hwloc-specific concepts, provides definitions, and discusses the
    00024  * "big picture" for many of the things that you'll find here in this
    00025  * header file.
    00026  *
    00027  * The PDF/HTML documentation was generated via Doxygen; much of what
    00028  * you'll see in there is also here in this file.  BUT THERE IS A LOT
    00029  * THAT IS IN THE PDF/HTML THAT IS ***NOT*** IN hwloc.h!
    00030  *
    00031  * There are entire paragraph-length descriptions, discussions, and
    00032  * pretty prictures to explain subtle corner cases, provide concrete
    00033  * examples, etc.
    00034  *
    00035  * Please, go read the documentation.  :-)
    00036  *
    00037  *=====================================================================*/
    00038
    00046 #ifndef HWLOC_H
    00047 #define HWLOC_H
    00048
    00049 #include <hwloc/autogen/config.h>
    00050 #include <sys/types.h>
    00051 #include <stdio.h>
    00052 #include <string.h>
    00053 #include <limits.h>
    00054
    00055 /*
    00056  * Symbol transforms
    00057  */
    00058 #include <hwloc/rename.h>
    00059
    00060 /*
    00061  * Bitmap definitions
    00062  */
    00063
    00064 #include <hwloc/bitmap.h>
    00065 #include <hwloc/cpuset.h>
    00066
    00067
    00068 #ifdef __cplusplus
    00069 extern "C" {
    00070 #endif
    00071
    00072
    00078 #define HWLOC_API_VERSION 0x00010200
    00079
    00081  unsigned hwloc_get_api_version(void);
    00082
    00091 struct hwloc_topology;
    00096 typedef struct hwloc_topology * hwloc_topology_t;
    00097
    00128 typedef hwloc_bitmap_t hwloc_cpuset_t;
    00130 typedef hwloc_const_bitmap_t hwloc_const_cpuset_t;
    00131
    00145 typedef hwloc_bitmap_t hwloc_nodeset_t;
    00148 typedef hwloc_const_bitmap_t hwloc_const_nodeset_t;
    00149
    00164 typedef enum {
    00165     /* ***************************************************************
    00166        WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
    00167
    00168        If new enum values are added here, you MUST also go update the
    00169        obj_type_order[] and obj_order_type[] arrays in src/topology.c.
    00170
    00171        WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
    00172        *************************************************************** */
    00173
    00174   HWLOC_OBJ_SYSTEM,
    00179   HWLOC_OBJ_MACHINE,
    00184   HWLOC_OBJ_NODE,
    00188   HWLOC_OBJ_SOCKET,
    00192   HWLOC_OBJ_CACHE,
    00195   HWLOC_OBJ_CORE,
    00199   HWLOC_OBJ_PU,
    00208   HWLOC_OBJ_GROUP,
    00220   HWLOC_OBJ_MISC,
    00225   HWLOC_OBJ_TYPE_MAX
    00227     /* ***************************************************************
    00228        WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
    00229
    00230        If new enum values are added here, you MUST also go update the
    00231        obj_type_order[] and obj_order_type[] arrays in src/topology.c.
    00232
    00233        WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
    00234        *************************************************************** */
    00235 } hwloc_obj_type_t;
    00236
    00254  int hwloc_compare_types (hwloc_obj_type_t type1, hwloc_obj_type_t type2) ;
    00255
    00256 enum hwloc_compare_types_e {
    00257     HWLOC_TYPE_UNORDERED = INT_MAX
    00258 };
    00259
    00268 union hwloc_obj_attr_u;
    00269
    00271 struct hwloc_obj_memory_s {
    00272   hwloc_uint64_t total_memory;
    00273   hwloc_uint64_t local_memory;
    00275   unsigned page_types_len;
    00281   struct hwloc_obj_memory_page_type_s {
    00282     hwloc_uint64_t size;
    00283     hwloc_uint64_t count;
    00284   } * page_types;
    00285 };
    00286
    00291 struct hwloc_obj {
    00292   /* physical information */
    00293   hwloc_obj_type_t type;
    00294   unsigned os_index;
    00295   char *name;
    00297   struct hwloc_obj_memory_s memory;
    00299   union hwloc_obj_attr_u *attr;
    00302   /* global position */
    00303   unsigned depth;
    00304   unsigned logical_index;
    00306   signed os_level;
    00308   /* cousins are all objects of the same type (and depth) across the entire topology */
    00309   struct hwloc_obj *next_cousin;
    00310   struct hwloc_obj *prev_cousin;
    00312   /* children of the same parent are siblings, even if they may have different type and depth */
    00313   struct hwloc_obj *parent;
    00314   unsigned sibling_rank;
    00315   struct hwloc_obj *next_sibling;
    00316   struct hwloc_obj *prev_sibling;
    00318   /* children array below this object */
    00319   unsigned arity;
    00320   struct hwloc_obj **children;
    00321   struct hwloc_obj *first_child;
    00322   struct hwloc_obj *last_child;
    00324   /* misc */
    00325   void *userdata;
    00327   /* cpusets and nodesets */
    00328   hwloc_cpuset_t cpuset;
    00341   hwloc_cpuset_t complete_cpuset;
    00352   hwloc_cpuset_t online_cpuset;
    00360   hwloc_cpuset_t allowed_cpuset;
    00371   hwloc_nodeset_t nodeset;
    00388   hwloc_nodeset_t complete_nodeset;
    00402   hwloc_nodeset_t allowed_nodeset;
    00415   struct hwloc_distances_s **distances;
    00416   unsigned distances_count;
    00417
    00418   struct hwloc_obj_info_s *infos;
    00419   unsigned infos_count;
    00420 };
    00424 typedef struct hwloc_obj * hwloc_obj_t;
    00425
    00427 union hwloc_obj_attr_u {
    00429   struct hwloc_cache_attr_s {
    00430     hwloc_uint64_t size;
    00431     unsigned depth;
    00432     unsigned linesize;
    00433   } cache;
    00435   struct hwloc_group_attr_s {
    00436     unsigned depth;
    00437   } group;
    00438 };
    00439
    00454 struct hwloc_distances_s {
    00455   unsigned relative_depth;
    00457   unsigned nbobjs;
    00462   float *latency;
    00467   float latency_max;
    00468   float latency_base;
    00472 };
    00473
    00475 struct hwloc_obj_info_s {
    00476   char *name;
    00477   char *value;
    00478 };
    00479
    00494  int hwloc_topology_init (hwloc_topology_t *topologyp);
    00495
    00508  int hwloc_topology_load(hwloc_topology_t topology);
    00509
    00514  void hwloc_topology_destroy (hwloc_topology_t topology);
    00515
    00527  void hwloc_topology_check(hwloc_topology_t topology);
    00528
    00561  int hwloc_topology_ignore_type(hwloc_topology_t topology, hwloc_obj_type_t type);
    00562
    00569  int hwloc_topology_ignore_type_keep_structure(hwloc_topology_t topology, hwloc_obj_type_t type);
    00570
    00576  int hwloc_topology_ignore_all_keep_structure(hwloc_topology_t topology);
    00577
    00582 enum hwloc_topology_flags_e {
    00583   HWLOC_TOPOLOGY_FLAG_WHOLE_SYSTEM = (1<<0),
    00592   HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM = (1<<1)
    00611 };
    00612
    00617  int hwloc_topology_set_flags (hwloc_topology_t topology, unsigned long flags);
    00618
    00637  int hwloc_topology_set_fsroot(hwloc_topology_t restrict topology, const char * restrict fsroot_path);
    00638
    00652  int hwloc_topology_set_pid(hwloc_topology_t restrict topology, hwloc_pid_t pid);
    00653
    00676  int hwloc_topology_set_synthetic(hwloc_topology_t restrict topology, const char * restrict description);
    00677
    00694  int hwloc_topology_set_xml(hwloc_topology_t restrict topology, const char * restrict xmlpath);
    00695
    00708  int hwloc_topology_set_xmlbuffer(hwloc_topology_t restrict topology, const char * restrict buffer, int size);
    00709
    00718  int hwloc_topology_set_distance_matrix(hwloc_topology_t restrict topology,
    00719                                                       hwloc_obj_type_t type, unsigned nbobjs,
    00720                                                       unsigned *os_index, float *distances);
    00721
    00723 struct hwloc_topology_discovery_support {
    00725   unsigned char pu;
    00726 };
    00727
    00729 struct hwloc_topology_cpubind_support {
    00731   unsigned char set_thisproc_cpubind;
    00733   unsigned char get_thisproc_cpubind;
    00735   unsigned char set_proc_cpubind;
    00737   unsigned char get_proc_cpubind;
    00739   unsigned char set_thisthread_cpubind;
    00741   unsigned char get_thisthread_cpubind;
    00743   unsigned char set_thread_cpubind;
    00745   unsigned char get_thread_cpubind;
    00747   unsigned char get_thisproc_last_cpu_location;
    00749   unsigned char get_proc_last_cpu_location;
    00751   unsigned char get_thisthread_last_cpu_location;
    00752 };
    00753
    00755 struct hwloc_topology_membind_support {
    00757   unsigned char set_thisproc_membind;
    00759   unsigned char get_thisproc_membind;
    00761   unsigned char set_proc_membind;
    00763   unsigned char get_proc_membind;
    00765   unsigned char set_thisthread_membind;
    00767   unsigned char get_thisthread_membind;
    00769   unsigned char set_area_membind;
    00771   unsigned char get_area_membind;
    00773   unsigned char alloc_membind;
    00775   unsigned char firsttouch_membind;
    00777   unsigned char bind_membind;
    00779   unsigned char interleave_membind;
    00781   unsigned char replicate_membind;
    00783   unsigned char nexttouch_membind;
    00784
    00786   unsigned char migrate_membind;
    00787 };
    00788
    00795 struct hwloc_topology_support {
    00796   struct hwloc_topology_discovery_support *discovery;
    00797   struct hwloc_topology_cpubind_support *cpubind;
    00798   struct hwloc_topology_membind_support *membind;
    00799 };
    00800
    00802  const struct hwloc_topology_support *hwloc_topology_get_support(hwloc_topology_t restrict topology);
    00803
    00816  void hwloc_topology_export_xml(hwloc_topology_t topology, const char *xmlpath);
    00817
    00824  void hwloc_topology_export_xmlbuffer(hwloc_topology_t topology, char **xmlbuffer, int *buflen);
    00825
    00837  hwloc_obj_t hwloc_topology_insert_misc_object_by_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, const char *name);
    00838
    00851  hwloc_obj_t hwloc_topology_insert_misc_object_by_parent(hwloc_topology_t topology, hwloc_obj_t parent, const char *name);
    00852
    00854 enum hwloc_restrict_flags_e {
    00855   HWLOC_RESTRICT_FLAG_ADAPT_DISTANCES = (1<<0),
    00860   HWLOC_RESTRICT_FLAG_ADAPT_MISC = (1<<1)
    00865 };
    00866
    00879  int hwloc_topology_restrict(hwloc_topology_t restrict topology, hwloc_const_cpuset_t cpuset, unsigned long flags);
    00880
    00898  unsigned hwloc_topology_get_depth(hwloc_topology_t restrict topology) ;
    00899
    00912  int hwloc_get_type_depth (hwloc_topology_t topology, hwloc_obj_type_t type);
    00913
    00914 enum hwloc_get_type_depth_e {
    00915     HWLOC_TYPE_DEPTH_UNKNOWN = -1,
    00916     HWLOC_TYPE_DEPTH_MULTIPLE = -2
    00917 };
    00918
    00923  hwloc_obj_type_t hwloc_get_depth_type (hwloc_topology_t topology, unsigned depth) ;
    00924
    00927  unsigned hwloc_get_nbobjs_by_depth (hwloc_topology_t topology, unsigned depth) ;
    00928
    00934 static inline int
    00935 hwloc_get_nbobjs_by_type (hwloc_topology_t topology, hwloc_obj_type_t type)
    00936 {
    00937         int depth = hwloc_get_type_depth(topology, type);
    00938         if (depth == HWLOC_TYPE_DEPTH_UNKNOWN)
    00939                 return 0;
    00940         if (depth == HWLOC_TYPE_DEPTH_MULTIPLE)
    00941                 return -1; /* FIXME: agregate nbobjs from different levels? */
    00942         return hwloc_get_nbobjs_by_depth(topology, depth);
    00943 }
    00944
    00952  int hwloc_topology_is_thissystem(hwloc_topology_t  restrict topology) ;
    00953
    00968  hwloc_obj_t hwloc_get_obj_by_depth (hwloc_topology_t topology, unsigned depth, unsigned idx) ;
    00969
    00976 static inline hwloc_obj_t
    00977 hwloc_get_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx)
    00978 {
    00979   int depth = hwloc_get_type_depth(topology, type);
    00980   if (depth == HWLOC_TYPE_DEPTH_UNKNOWN)
    00981     return NULL;
    00982   if (depth == HWLOC_TYPE_DEPTH_MULTIPLE)
    00983     return NULL;
    00984   return hwloc_get_obj_by_depth(topology, depth, idx);
    00985 }
    00986
    00996  const char * hwloc_obj_type_string (hwloc_obj_type_t type) ;
    00997
    01002  hwloc_obj_type_t hwloc_obj_type_of_string (const char * string) ;
    01003
    01014  int hwloc_obj_type_snprintf(char * restrict string, size_t size, hwloc_obj_t obj,
    01015                                    int verbose);
    01016
    01028  int hwloc_obj_attr_snprintf(char * restrict string, size_t size, hwloc_obj_t obj, const char * restrict separator,
    01029                                    int verbose);
    01030
    01051  int hwloc_obj_snprintf(char * restrict string, size_t size,
    01052                              hwloc_topology_t topology, hwloc_obj_t obj,
    01053                              const char * restrict indexprefix, int verbose);
    01054
    01062  int hwloc_obj_cpuset_snprintf(char * restrict str, size_t size, size_t nobj, const hwloc_obj_t * restrict objs);
    01063
    01068 static inline char *
    01069 hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name)
    01070 {
    01071   unsigned i;
    01072   for(i=0; i<obj->infos_count; i++)
    01073     if (!strcmp(obj->infos[i].name, name))
    01074       return obj->infos[i].value;
    01075   return NULL;
    01076 }
    01077
    01135 typedef enum {
    01136   HWLOC_CPUBIND_PROCESS = (1<<0),
    01139   HWLOC_CPUBIND_THREAD = (1<<1),
    01141   HWLOC_CPUBIND_STRICT = (1<<2),
    01169   HWLOC_CPUBIND_NOMEMBIND = (1<<3)
    01189 } hwloc_cpubind_flags_t;
    01190
    01196  int hwloc_set_cpubind(hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags);
    01197
    01203  int hwloc_get_cpubind(hwloc_topology_t topology, hwloc_cpuset_t set, int flags);
    01204
    01212  int hwloc_set_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_cpuset_t set, int flags);
    01213
    01225  int hwloc_get_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags);
    01226
    01227 #ifdef hwloc_thread_t
    01228
    01235  int hwloc_set_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_const_cpuset_t set, int flags);
    01236 #endif
    01237
    01238 #ifdef hwloc_thread_t
    01239
    01246  int hwloc_get_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t tid, hwloc_cpuset_t set, int flags);
    01247 #endif
    01248
    01256  int hwloc_get_last_cpu_location(hwloc_topology_t topology, hwloc_cpuset_t set, int flags);
    01257
    01271  int hwloc_get_proc_last_cpu_location(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags);
    01272
    01331 typedef enum {
    01332   HWLOC_MEMBIND_DEFAULT =       0,
    01334   HWLOC_MEMBIND_FIRSTTOUCH =    1,
    01345   HWLOC_MEMBIND_BIND =          2,
    01347   HWLOC_MEMBIND_INTERLEAVE =    3,
    01362   HWLOC_MEMBIND_REPLICATE =     4,
    01384   HWLOC_MEMBIND_NEXTTOUCH =     5,
    01394   HWLOC_MEMBIND_MIXED = -1
    01399 } hwloc_membind_policy_t;
    01400
    01412 typedef enum {
    01413   HWLOC_MEMBIND_PROCESS =       (1<<0),
    01420   HWLOC_MEMBIND_THREAD =        (1<<1),
    01426   HWLOC_MEMBIND_STRICT =        (1<<2),
    01437   HWLOC_MEMBIND_MIGRATE =       (1<<3),
    01445   HWLOC_MEMBIND_NOCPUBIND =     (1<<4)
    01468 } hwloc_membind_flags_t;
    01469
    01482  int hwloc_set_membind_nodeset(hwloc_topology_t topology, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags);
    01483
    01497  int hwloc_set_membind(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags);
    01498
    01539  int hwloc_get_membind_nodeset(hwloc_topology_t topology, hwloc_nodeset_t nodeset, hwloc_membind_policy_t * policy, int flags);
    01540
    01586  int hwloc_get_membind(hwloc_topology_t topology, hwloc_cpuset_t cpuset, hwloc_membind_policy_t * policy, int flags);
    01587
    01594  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);
    01595
    01602  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);
    01603
    01637  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);
    01638
    01675  int hwloc_get_proc_membind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t cpuset, hwloc_membind_policy_t * policy, int flags);
    01676
    01683  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);
    01684
    01691  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);
    01692
    01715  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);
    01716
    01741  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);
    01742
    01750  void *hwloc_alloc(hwloc_topology_t topology, size_t len);
    01751
    01761  void *hwloc_alloc_membind_nodeset(hwloc_topology_t topology, size_t len, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags) ;
    01762
    01772  void *hwloc_alloc_membind(hwloc_topology_t topology, size_t len, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags) ;
    01773
    01777  int hwloc_free(hwloc_topology_t topology, void *addr, size_t len);
    01778
    01782 #ifdef __cplusplus
    01783 } /* extern "C" */
    01784 #endif
    01785
    01786
    01787 /* high-level helpers */
    01788 #include <hwloc/helper.h>
    01789
    01790
    01791 #endif /* HWLOC_H */