Hardware Locality (hwloc) 1.2.2
|
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 */