Open MPI logo

Portable Hardware Locality (hwloc) Documentation: v1.1.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 0x00010100
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   HWLOC_OBJ_SYSTEM,     
00140   HWLOC_OBJ_MACHINE,    
00145   HWLOC_OBJ_NODE,       
00149   HWLOC_OBJ_SOCKET,     
00153   HWLOC_OBJ_CACHE,      
00156   HWLOC_OBJ_CORE,       
00160   HWLOC_OBJ_PU,         
00169   HWLOC_OBJ_GROUP,      
00181   HWLOC_OBJ_MISC        
00185 } hwloc_obj_type_t;
00186 
00204  int hwloc_compare_types (hwloc_obj_type_t type1, hwloc_obj_type_t type2) ;
00205 
00206 enum hwloc_compare_types_e {
00207     HWLOC_TYPE_UNORDERED = INT_MAX      
00208 };
00209 
00218 union hwloc_obj_attr_u;
00219 
00221 struct hwloc_obj_memory_s {
00222   hwloc_uint64_t total_memory; 
00223   hwloc_uint64_t local_memory; 
00225   unsigned page_types_len; 
00231   struct hwloc_obj_memory_page_type_s {
00232     hwloc_uint64_t size;        
00233     hwloc_uint64_t count;       
00234   } * page_types;
00235 };
00236 
00241 struct hwloc_obj {
00242   /* physical information */
00243   hwloc_obj_type_t type;                
00244   unsigned os_index;                    
00245   char *name;                           
00247   struct hwloc_obj_memory_s memory;     
00249   union hwloc_obj_attr_u *attr;         
00252   /* global position */
00253   unsigned depth;                       
00254   unsigned logical_index;               
00256   signed os_level;                      
00258   struct hwloc_obj *next_cousin;        
00259   struct hwloc_obj *prev_cousin;        
00261   /* parent */
00262   struct hwloc_obj *parent;             
00263   unsigned sibling_rank;                
00264   struct hwloc_obj *next_sibling;       
00265   struct hwloc_obj *prev_sibling;       
00267   /* children */
00268   unsigned arity;                       
00269   struct hwloc_obj **children;          
00270   struct hwloc_obj *first_child;        
00271   struct hwloc_obj *last_child;         
00273   /* misc */
00274   void *userdata;                       
00276   /* cpusets and nodesets */
00277   hwloc_cpuset_t cpuset;                
00290   hwloc_cpuset_t complete_cpuset;       
00301   hwloc_cpuset_t online_cpuset;         
00309   hwloc_cpuset_t allowed_cpuset;        
00320   hwloc_nodeset_t nodeset;              
00337   hwloc_nodeset_t complete_nodeset;     
00351   hwloc_nodeset_t allowed_nodeset;      
00364   struct hwloc_obj_info_s *infos;       
00365   unsigned infos_count;                 
00366 };
00370 typedef struct hwloc_obj * hwloc_obj_t;
00371 
00373 union hwloc_obj_attr_u {
00375   struct hwloc_cache_attr_s {
00376     hwloc_uint64_t size;                          
00377     unsigned depth;                       
00378     unsigned linesize;                    
00379   } cache;
00381   struct hwloc_group_attr_s {
00382     unsigned depth;                       
00383   } group;
00384 };
00385 
00387 struct hwloc_obj_info_s {
00388   char *name;   
00389   char *value;  
00390 };
00391 
00406  int hwloc_topology_init (hwloc_topology_t *topologyp);
00407 
00420  int hwloc_topology_load(hwloc_topology_t topology);
00421 
00426  void hwloc_topology_destroy (hwloc_topology_t topology);
00427 
00432  void hwloc_topology_check(hwloc_topology_t topology);
00433 
00466  int hwloc_topology_ignore_type(hwloc_topology_t topology, hwloc_obj_type_t type);
00467 
00474  int hwloc_topology_ignore_type_keep_structure(hwloc_topology_t topology, hwloc_obj_type_t type);
00475 
00481  int hwloc_topology_ignore_all_keep_structure(hwloc_topology_t topology);
00482 
00487 enum hwloc_topology_flags_e {
00488   HWLOC_TOPOLOGY_FLAG_WHOLE_SYSTEM = (1<<0),
00497   HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM = (1<<1)
00516 };
00517 
00522  int hwloc_topology_set_flags (hwloc_topology_t topology, unsigned long flags);
00523 
00537  int hwloc_topology_set_fsroot(hwloc_topology_t restrict topology, const char * restrict fsroot_path);
00538 
00552  int hwloc_topology_set_pid(hwloc_topology_t restrict topology, hwloc_pid_t pid);
00553 
00571  int hwloc_topology_set_synthetic(hwloc_topology_t restrict topology, const char * restrict description);
00572 
00584  int hwloc_topology_set_xml(hwloc_topology_t restrict topology, const char * restrict xmlpath);
00585 
00591  int hwloc_topology_set_xmlbuffer(hwloc_topology_t restrict topology, const char * restrict buffer, int size);
00592 
00594 struct hwloc_topology_discovery_support {
00596   unsigned char pu;
00597 };
00598 
00600 struct hwloc_topology_cpubind_support {
00602   unsigned char set_thisproc_cpubind;
00604   unsigned char get_thisproc_cpubind;
00606   unsigned char set_proc_cpubind;
00608   unsigned char get_proc_cpubind;
00610   unsigned char set_thisthread_cpubind;
00612   unsigned char get_thisthread_cpubind;
00614   unsigned char set_thread_cpubind;
00616   unsigned char get_thread_cpubind;
00617 };
00618 
00620 struct hwloc_topology_membind_support {
00622   unsigned char set_thisproc_membind;
00624   unsigned char get_thisproc_membind;
00626   unsigned char set_proc_membind;
00628   unsigned char get_proc_membind;
00630   unsigned char set_thisthread_membind;
00632   unsigned char get_thisthread_membind;
00634   unsigned char set_area_membind;
00636   unsigned char get_area_membind;
00638   unsigned char alloc_membind;
00640   unsigned char firsttouch_membind;
00642   unsigned char bind_membind;
00644   unsigned char interleave_membind;
00646   unsigned char replicate_membind;
00648   unsigned char nexttouch_membind;
00649 
00651   unsigned char migrate_membind;
00652 };
00653 
00660 struct hwloc_topology_support {
00661   struct hwloc_topology_discovery_support *discovery;
00662   struct hwloc_topology_cpubind_support *cpubind;
00663   struct hwloc_topology_membind_support *membind;
00664 };
00665 
00667  const struct hwloc_topology_support *hwloc_topology_get_support(hwloc_topology_t restrict topology);
00668 
00681  void hwloc_topology_export_xml(hwloc_topology_t topology, const char *xmlpath);
00682 
00689  void hwloc_topology_export_xmlbuffer(hwloc_topology_t topology, char **xmlbuffer, int *buflen);
00690 
00700  hwloc_obj_t hwloc_topology_insert_misc_object_by_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, const char *name);
00701 
00711  hwloc_obj_t hwloc_topology_insert_misc_object_by_parent(hwloc_topology_t topology, hwloc_obj_t parent, const char *name);
00712 
00725  unsigned hwloc_topology_get_depth(hwloc_topology_t restrict topology) ;
00726 
00739  int hwloc_get_type_depth (hwloc_topology_t topology, hwloc_obj_type_t type);
00740 
00741 enum hwloc_get_type_depth_e {
00742     HWLOC_TYPE_DEPTH_UNKNOWN = -1, 
00743     HWLOC_TYPE_DEPTH_MULTIPLE = -2 
00744 };
00745 
00750  hwloc_obj_type_t hwloc_get_depth_type (hwloc_topology_t topology, unsigned depth) ;
00751 
00753  unsigned hwloc_get_nbobjs_by_depth (hwloc_topology_t topology, unsigned depth) ;
00754 
00760 static inline int 
00761 hwloc_get_nbobjs_by_type (hwloc_topology_t topology, hwloc_obj_type_t type)
00762 {
00763         int depth = hwloc_get_type_depth(topology, type);
00764         if (depth == HWLOC_TYPE_DEPTH_UNKNOWN)
00765                 return 0;
00766         if (depth == HWLOC_TYPE_DEPTH_MULTIPLE)
00767                 return -1; /* FIXME: agregate nbobjs from different levels? */
00768         return hwloc_get_nbobjs_by_depth(topology, depth);
00769 }
00770 
00778  int hwloc_topology_is_thissystem(hwloc_topology_t  restrict topology) ;
00779 
00789  hwloc_obj_t hwloc_get_obj_by_depth (hwloc_topology_t topology, unsigned depth, unsigned idx) ;
00790 
00797 static inline hwloc_obj_t 
00798 hwloc_get_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx)
00799 {
00800   int depth = hwloc_get_type_depth(topology, type);
00801   if (depth == HWLOC_TYPE_DEPTH_UNKNOWN)
00802     return NULL;
00803   if (depth == HWLOC_TYPE_DEPTH_MULTIPLE)
00804     return NULL;
00805   return hwloc_get_obj_by_depth(topology, depth, idx);
00806 }
00807 
00817  const char * hwloc_obj_type_string (hwloc_obj_type_t type) ;
00818 
00823  hwloc_obj_type_t hwloc_obj_type_of_string (const char * string) ;
00824 
00835  int hwloc_obj_type_snprintf(char * restrict string, size_t size, hwloc_obj_t obj,
00836                                    int verbose);
00837 
00849  int hwloc_obj_attr_snprintf(char * restrict string, size_t size, hwloc_obj_t obj, const char * restrict separator,
00850                                    int verbose);
00851 
00872  int hwloc_obj_snprintf(char * restrict string, size_t size,
00873                              hwloc_topology_t topology, hwloc_obj_t obj,
00874                              const char * restrict indexprefix, int verbose);
00875 
00883  int hwloc_obj_cpuset_snprintf(char * restrict str, size_t size, size_t nobj, const hwloc_obj_t * restrict objs);
00884 
00889 static inline char * 
00890 hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name)
00891 {
00892   unsigned i;
00893   for(i=0; i<obj->infos_count; i++)
00894     if (!strcmp(obj->infos[i].name, name))
00895       return obj->infos[i].value;
00896   return NULL;
00897 }
00898 
00953 typedef enum {
00954   HWLOC_CPUBIND_PROCESS = (1<<0), 
00957   HWLOC_CPUBIND_THREAD = (1<<1),  
00959   HWLOC_CPUBIND_STRICT = (1<<2),  
00987   HWLOC_CPUBIND_NOMEMBIND = (1<<3)
01001 } hwloc_cpubind_flags_t;
01002 
01008  int hwloc_set_cpubind(hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags);
01009 
01012  int hwloc_get_cpubind(hwloc_topology_t topology, hwloc_cpuset_t set, int flags);
01013 
01021  int hwloc_set_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_cpuset_t set, int flags);
01022 
01030  int hwloc_get_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags);
01031 
01032 #ifdef hwloc_thread_t
01033 
01040  int hwloc_set_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t tid, hwloc_const_cpuset_t set, int flags);
01041 #endif
01042 
01043 #ifdef hwloc_thread_t
01044 
01051  int hwloc_get_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t tid, hwloc_cpuset_t set, int flags);
01052 #endif
01053 
01112 typedef enum {
01113   HWLOC_MEMBIND_DEFAULT =       0,      
01115   HWLOC_MEMBIND_FIRSTTOUCH =    1,      
01126   HWLOC_MEMBIND_BIND =          2,      
01128   HWLOC_MEMBIND_INTERLEAVE =    3,      
01143   HWLOC_MEMBIND_REPLICATE =     4,      
01165   HWLOC_MEMBIND_NEXTTOUCH =     5,      
01175   HWLOC_MEMBIND_MIXED = -1              
01180 } hwloc_membind_policy_t;
01181 
01193 typedef enum {
01194   HWLOC_MEMBIND_PROCESS =       (1<<0), 
01201   HWLOC_MEMBIND_THREAD =        (1<<1), 
01207   HWLOC_MEMBIND_STRICT =        (1<<2), 
01218   HWLOC_MEMBIND_MIGRATE =       (1<<3), 
01226   HWLOC_MEMBIND_NOCPUBIND =     (1<<4)  
01249 } hwloc_membind_flags_t;
01250 
01263  int hwloc_set_membind_nodeset(hwloc_topology_t topology, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags);
01264 
01278  int hwloc_set_membind(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags);
01279 
01320  int hwloc_get_membind_nodeset(hwloc_topology_t topology, hwloc_nodeset_t nodeset, hwloc_membind_policy_t * policy, int flags);
01321 
01367  int hwloc_get_membind(hwloc_topology_t topology, hwloc_cpuset_t cpuset, hwloc_membind_policy_t * policy, int flags);
01368 
01375  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);
01376 
01383  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);
01384 
01418  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);
01419 
01456  int hwloc_get_proc_membind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t cpuset, hwloc_membind_policy_t * policy, int flags);
01457 
01464  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);
01465 
01472  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);
01473 
01496  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);
01497 
01522  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);
01523 
01531  void *hwloc_alloc(hwloc_topology_t topology, size_t len);
01532 
01542  void *hwloc_alloc_membind_nodeset(hwloc_topology_t topology, size_t len, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags) ;
01543 
01553  void *hwloc_alloc_membind(hwloc_topology_t topology, size_t len, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags) ;
01554 
01558  int hwloc_free(hwloc_topology_t topology, void *addr, size_t len);
01559 
01563 #ifdef __cplusplus
01564 } /* extern "C" */
01565 #endif
01566 
01567 
01568 /* high-level helpers */
01569 #include <hwloc/helper.h>
01570 
01571 
01572 #endif /* HWLOC_H */