Open MPI logo

Portable Hardware Locality (hwloc) Documentation: v1.2

  |   Home   |   Support   |   FAQ   |  

hwloc.h

Go to the documentation of this file.
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 
00016 #ifndef HWLOC_H
00017 #define HWLOC_H
00018 
00019 #include <hwloc/autogen/config.h>
00020 #include <sys/types.h>
00021 #include <stdio.h>
00022 #include <string.h>
00023 #include <limits.h>
00024 
00025 /*
00026  * Symbol transforms
00027  */
00028 #include <hwloc/rename.h>
00029 
00030 /*
00031  * Bitmap definitions
00032  */
00033 
00034 #include <hwloc/bitmap.h>
00035 #include <hwloc/cpuset.h>
00036 
00037 
00038 #ifdef __cplusplus
00039 extern "C" {
00040 #endif
00041 
00042 
00048 #define HWLOC_API_VERSION 0x00010200
00049 
00051  unsigned hwloc_get_api_version(void);
00052 
00061 struct hwloc_topology;
00066 typedef struct hwloc_topology * hwloc_topology_t;
00067 
00098 typedef hwloc_bitmap_t hwloc_cpuset_t;
00100 typedef hwloc_const_bitmap_t hwloc_const_cpuset_t;
00101 
00115 typedef hwloc_bitmap_t hwloc_nodeset_t;
00118 typedef hwloc_const_bitmap_t hwloc_const_nodeset_t;
00119 
00134 typedef enum {
00135     /* ***************************************************************
00136        WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
00137 
00138        If new enum values are added here, you MUST also go update the
00139        obj_type_order[] and obj_order_type[] arrays in src/topology.c.
00140 
00141        WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
00142        *************************************************************** */
00143 
00144   HWLOC_OBJ_SYSTEM,     
00149   HWLOC_OBJ_MACHINE,    
00154   HWLOC_OBJ_NODE,       
00158   HWLOC_OBJ_SOCKET,     
00162   HWLOC_OBJ_CACHE,      
00165   HWLOC_OBJ_CORE,       
00169   HWLOC_OBJ_PU,         
00178   HWLOC_OBJ_GROUP,      
00190   HWLOC_OBJ_MISC,       
00195   HWLOC_OBJ_TYPE_MAX    
00197     /* ***************************************************************
00198        WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
00199 
00200        If new enum values are added here, you MUST also go update the
00201        obj_type_order[] and obj_order_type[] arrays in src/topology.c.
00202 
00203        WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
00204        *************************************************************** */
00205 } hwloc_obj_type_t;
00206 
00224  int hwloc_compare_types (hwloc_obj_type_t type1, hwloc_obj_type_t type2) ;
00225 
00226 enum hwloc_compare_types_e {
00227     HWLOC_TYPE_UNORDERED = INT_MAX      
00228 };
00229 
00238 union hwloc_obj_attr_u;
00239 
00241 struct hwloc_obj_memory_s {
00242   hwloc_uint64_t total_memory; 
00243   hwloc_uint64_t local_memory; 
00245   unsigned page_types_len; 
00251   struct hwloc_obj_memory_page_type_s {
00252     hwloc_uint64_t size;        
00253     hwloc_uint64_t count;       
00254   } * page_types;
00255 };
00256 
00261 struct hwloc_obj {
00262   /* physical information */
00263   hwloc_obj_type_t type;                
00264   unsigned os_index;                    
00265   char *name;                           
00267   struct hwloc_obj_memory_s memory;     
00269   union hwloc_obj_attr_u *attr;         
00272   /* global position */
00273   unsigned depth;                       
00274   unsigned logical_index;               
00276   signed os_level;                      
00278   /* cousins are all objects of the same type (and depth) across the entire topology */
00279   struct hwloc_obj *next_cousin;        
00280   struct hwloc_obj *prev_cousin;        
00282   /* children of the same parent are siblings, even if they may have different type and depth */
00283   struct hwloc_obj *parent;             
00284   unsigned sibling_rank;                
00285   struct hwloc_obj *next_sibling;       
00286   struct hwloc_obj *prev_sibling;       
00288   /* children array below this object */
00289   unsigned arity;                       
00290   struct hwloc_obj **children;          
00291   struct hwloc_obj *first_child;        
00292   struct hwloc_obj *last_child;         
00294   /* misc */
00295   void *userdata;                       
00297   /* cpusets and nodesets */
00298   hwloc_cpuset_t cpuset;                
00311   hwloc_cpuset_t complete_cpuset;       
00322   hwloc_cpuset_t online_cpuset;         
00330   hwloc_cpuset_t allowed_cpuset;        
00341   hwloc_nodeset_t nodeset;              
00358   hwloc_nodeset_t complete_nodeset;     
00372   hwloc_nodeset_t allowed_nodeset;      
00385   struct hwloc_distances_s **distances; 
00386   unsigned distances_count;
00387 
00388   struct hwloc_obj_info_s *infos;       
00389   unsigned infos_count;                 
00390 };
00394 typedef struct hwloc_obj * hwloc_obj_t;
00395 
00397 union hwloc_obj_attr_u {
00399   struct hwloc_cache_attr_s {
00400     hwloc_uint64_t size;                          
00401     unsigned depth;                       
00402     unsigned linesize;                    
00403   } cache;
00405   struct hwloc_group_attr_s {
00406     unsigned depth;                       
00407   } group;
00408 };
00409 
00424 struct hwloc_distances_s {
00425   unsigned relative_depth;      
00427   unsigned nbobjs;              
00432   float *latency;               
00437   float latency_max;            
00438   float latency_base;           
00442 };
00443 
00445 struct hwloc_obj_info_s {
00446   char *name;   
00447   char *value;  
00448 };
00449 
00464  int hwloc_topology_init (hwloc_topology_t *topologyp);
00465 
00478  int hwloc_topology_load(hwloc_topology_t topology);
00479 
00484  void hwloc_topology_destroy (hwloc_topology_t topology);
00485 
00490  void hwloc_topology_check(hwloc_topology_t topology);
00491 
00524  int hwloc_topology_ignore_type(hwloc_topology_t topology, hwloc_obj_type_t type);
00525 
00532  int hwloc_topology_ignore_type_keep_structure(hwloc_topology_t topology, hwloc_obj_type_t type);
00533 
00539  int hwloc_topology_ignore_all_keep_structure(hwloc_topology_t topology);
00540 
00545 enum hwloc_topology_flags_e {
00546   HWLOC_TOPOLOGY_FLAG_WHOLE_SYSTEM = (1<<0),
00555   HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM = (1<<1)
00574 };
00575 
00580  int hwloc_topology_set_flags (hwloc_topology_t topology, unsigned long flags);
00581 
00595  int hwloc_topology_set_fsroot(hwloc_topology_t restrict topology, const char * restrict fsroot_path);
00596 
00610  int hwloc_topology_set_pid(hwloc_topology_t restrict topology, hwloc_pid_t pid);
00611 
00629  int hwloc_topology_set_synthetic(hwloc_topology_t restrict topology, const char * restrict description);
00630 
00642  int hwloc_topology_set_xml(hwloc_topology_t restrict topology, const char * restrict xmlpath);
00643 
00649  int hwloc_topology_set_xmlbuffer(hwloc_topology_t restrict topology, const char * restrict buffer, int size);
00650 
00659  int hwloc_topology_set_distance_matrix(hwloc_topology_t restrict topology,
00660                                                       hwloc_obj_type_t type, unsigned nbobjs,
00661                                                       unsigned *os_index, float *distances);
00662 
00664 struct hwloc_topology_discovery_support {
00666   unsigned char pu;
00667 };
00668 
00670 struct hwloc_topology_cpubind_support {
00672   unsigned char set_thisproc_cpubind;
00674   unsigned char get_thisproc_cpubind;
00676   unsigned char set_proc_cpubind;
00678   unsigned char get_proc_cpubind;
00680   unsigned char set_thisthread_cpubind;
00682   unsigned char get_thisthread_cpubind;
00684   unsigned char set_thread_cpubind;
00686   unsigned char get_thread_cpubind;
00688   unsigned char get_thisproc_last_cpu_location;
00690   unsigned char get_proc_last_cpu_location;
00692   unsigned char get_thisthread_last_cpu_location;
00693 };
00694 
00696 struct hwloc_topology_membind_support {
00698   unsigned char set_thisproc_membind;
00700   unsigned char get_thisproc_membind;
00702   unsigned char set_proc_membind;
00704   unsigned char get_proc_membind;
00706   unsigned char set_thisthread_membind;
00708   unsigned char get_thisthread_membind;
00710   unsigned char set_area_membind;
00712   unsigned char get_area_membind;
00714   unsigned char alloc_membind;
00716   unsigned char firsttouch_membind;
00718   unsigned char bind_membind;
00720   unsigned char interleave_membind;
00722   unsigned char replicate_membind;
00724   unsigned char nexttouch_membind;
00725 
00727   unsigned char migrate_membind;
00728 };
00729 
00736 struct hwloc_topology_support {
00737   struct hwloc_topology_discovery_support *discovery;
00738   struct hwloc_topology_cpubind_support *cpubind;
00739   struct hwloc_topology_membind_support *membind;
00740 };
00741 
00743  const struct hwloc_topology_support *hwloc_topology_get_support(hwloc_topology_t restrict topology);
00744 
00757  void hwloc_topology_export_xml(hwloc_topology_t topology, const char *xmlpath);
00758 
00765  void hwloc_topology_export_xmlbuffer(hwloc_topology_t topology, char **xmlbuffer, int *buflen);
00766 
00778  hwloc_obj_t hwloc_topology_insert_misc_object_by_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, const char *name);
00779 
00792  hwloc_obj_t hwloc_topology_insert_misc_object_by_parent(hwloc_topology_t topology, hwloc_obj_t parent, const char *name);
00793 
00795 enum hwloc_restrict_flags_e {
00796   HWLOC_RESTRICT_FLAG_ADAPT_DISTANCES = (1<<0),
00801   HWLOC_RESTRICT_FLAG_ADAPT_MISC = (1<<1)
00806 };
00807 
00820  int hwloc_topology_restrict(hwloc_topology_t restrict topology, hwloc_const_cpuset_t cpuset, unsigned long flags);
00821 
00834  unsigned hwloc_topology_get_depth(hwloc_topology_t restrict topology) ;
00835 
00848  int hwloc_get_type_depth (hwloc_topology_t topology, hwloc_obj_type_t type);
00849 
00850 enum hwloc_get_type_depth_e {
00851     HWLOC_TYPE_DEPTH_UNKNOWN = -1, 
00852     HWLOC_TYPE_DEPTH_MULTIPLE = -2 
00853 };
00854 
00859  hwloc_obj_type_t hwloc_get_depth_type (hwloc_topology_t topology, unsigned depth) ;
00860 
00862  unsigned hwloc_get_nbobjs_by_depth (hwloc_topology_t topology, unsigned depth) ;
00863 
00869 static inline int 
00870 hwloc_get_nbobjs_by_type (hwloc_topology_t topology, hwloc_obj_type_t type)
00871 {
00872         int depth = hwloc_get_type_depth(topology, type);
00873         if (depth == HWLOC_TYPE_DEPTH_UNKNOWN)
00874                 return 0;
00875         if (depth == HWLOC_TYPE_DEPTH_MULTIPLE)
00876                 return -1; /* FIXME: agregate nbobjs from different levels? */
00877         return hwloc_get_nbobjs_by_depth(topology, depth);
00878 }
00879 
00887  int hwloc_topology_is_thissystem(hwloc_topology_t  restrict topology) ;
00888 
00898  hwloc_obj_t hwloc_get_obj_by_depth (hwloc_topology_t topology, unsigned depth, unsigned idx) ;
00899 
00906 static inline hwloc_obj_t 
00907 hwloc_get_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx)
00908 {
00909   int depth = hwloc_get_type_depth(topology, type);
00910   if (depth == HWLOC_TYPE_DEPTH_UNKNOWN)
00911     return NULL;
00912   if (depth == HWLOC_TYPE_DEPTH_MULTIPLE)
00913     return NULL;
00914   return hwloc_get_obj_by_depth(topology, depth, idx);
00915 }
00916 
00926  const char * hwloc_obj_type_string (hwloc_obj_type_t type) ;
00927 
00932  hwloc_obj_type_t hwloc_obj_type_of_string (const char * string) ;
00933 
00944  int hwloc_obj_type_snprintf(char * restrict string, size_t size, hwloc_obj_t obj,
00945                                    int verbose);
00946 
00958  int hwloc_obj_attr_snprintf(char * restrict string, size_t size, hwloc_obj_t obj, const char * restrict separator,
00959                                    int verbose);
00960 
00981  int hwloc_obj_snprintf(char * restrict string, size_t size,
00982                              hwloc_topology_t topology, hwloc_obj_t obj,
00983                              const char * restrict indexprefix, int verbose);
00984 
00992  int hwloc_obj_cpuset_snprintf(char * restrict str, size_t size, size_t nobj, const hwloc_obj_t * restrict objs);
00993 
00998 static inline char * 
00999 hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name)
01000 {
01001   unsigned i;
01002   for(i=0; i<obj->infos_count; i++)
01003     if (!strcmp(obj->infos[i].name, name))
01004       return obj->infos[i].value;
01005   return NULL;
01006 }
01007 
01062 typedef enum {
01063   HWLOC_CPUBIND_PROCESS = (1<<0), 
01066   HWLOC_CPUBIND_THREAD = (1<<1),  
01068   HWLOC_CPUBIND_STRICT = (1<<2),  
01096   HWLOC_CPUBIND_NOMEMBIND = (1<<3)
01110 } hwloc_cpubind_flags_t;
01111 
01117  int hwloc_set_cpubind(hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags);
01118 
01121  int hwloc_get_cpubind(hwloc_topology_t topology, hwloc_cpuset_t set, int flags);
01122 
01130  int hwloc_set_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_cpuset_t set, int flags);
01131 
01139  int hwloc_get_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags);
01140 
01141 #ifdef hwloc_thread_t
01142 
01149  int hwloc_set_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t tid, hwloc_const_cpuset_t set, int flags);
01150 #endif
01151 
01152 #ifdef hwloc_thread_t
01153 
01160  int hwloc_get_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t tid, hwloc_cpuset_t set, int flags);
01161 #endif
01162 
01170  int hwloc_get_last_cpu_location(hwloc_topology_t topology, hwloc_cpuset_t set, int flags);
01171 
01181  int hwloc_get_proc_last_cpu_location(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags);
01182 
01241 typedef enum {
01242   HWLOC_MEMBIND_DEFAULT =       0,      
01244   HWLOC_MEMBIND_FIRSTTOUCH =    1,      
01255   HWLOC_MEMBIND_BIND =          2,      
01257   HWLOC_MEMBIND_INTERLEAVE =    3,      
01272   HWLOC_MEMBIND_REPLICATE =     4,      
01294   HWLOC_MEMBIND_NEXTTOUCH =     5,      
01304   HWLOC_MEMBIND_MIXED = -1              
01309 } hwloc_membind_policy_t;
01310 
01322 typedef enum {
01323   HWLOC_MEMBIND_PROCESS =       (1<<0), 
01330   HWLOC_MEMBIND_THREAD =        (1<<1), 
01336   HWLOC_MEMBIND_STRICT =        (1<<2), 
01347   HWLOC_MEMBIND_MIGRATE =       (1<<3), 
01355   HWLOC_MEMBIND_NOCPUBIND =     (1<<4)  
01378 } hwloc_membind_flags_t;
01379 
01392  int hwloc_set_membind_nodeset(hwloc_topology_t topology, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags);
01393 
01407  int hwloc_set_membind(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags);
01408 
01449  int hwloc_get_membind_nodeset(hwloc_topology_t topology, hwloc_nodeset_t nodeset, hwloc_membind_policy_t * policy, int flags);
01450 
01496  int hwloc_get_membind(hwloc_topology_t topology, hwloc_cpuset_t cpuset, hwloc_membind_policy_t * policy, int flags);
01497 
01504  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);
01505 
01512  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);
01513 
01547  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);
01548 
01585  int hwloc_get_proc_membind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t cpuset, hwloc_membind_policy_t * policy, int flags);
01586 
01593  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);
01594 
01601  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);
01602 
01625  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);
01626 
01651  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);
01652 
01660  void *hwloc_alloc(hwloc_topology_t topology, size_t len);
01661 
01671  void *hwloc_alloc_membind_nodeset(hwloc_topology_t topology, size_t len, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags) ;
01672 
01682  void *hwloc_alloc_membind(hwloc_topology_t topology, size_t len, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags) ;
01683 
01687  int hwloc_free(hwloc_topology_t topology, void *addr, size_t len);
01688 
01692 #ifdef __cplusplus
01693 } /* extern "C" */
01694 #endif
01695 
01696 
01697 /* high-level helpers */
01698 #include <hwloc/helper.h>
01699 
01700 
01701 #endif /* HWLOC_H */