Open MPI logo

Portable Hardware Locality (hwloc) Documentation: v1.2.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 
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 */