Hardware Locality (hwloc) 1.3.1
|
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 0x00010300 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_BRIDGE, 00232 HWLOC_OBJ_PCI_DEVICE, 00237 HWLOC_OBJ_OS_DEVICE, 00243 HWLOC_OBJ_TYPE_MAX 00245 /* *************************************************************** 00246 WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING 00247 00248 If new enum values are added here, you MUST also go update the 00249 obj_type_order[] and obj_order_type[] arrays in src/topology.c. 00250 00251 WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING 00252 *************************************************************** */ 00253 } hwloc_obj_type_t; 00254 00256 typedef enum hwloc_obj_bridge_type_e { 00257 HWLOC_OBJ_BRIDGE_HOST, 00258 HWLOC_OBJ_BRIDGE_PCI 00259 } hwloc_obj_bridge_type_t; 00260 00262 typedef enum hwloc_obj_osdev_type_e { 00263 HWLOC_OBJ_OSDEV_BLOCK, 00265 HWLOC_OBJ_OSDEV_GPU, 00267 HWLOC_OBJ_OSDEV_NETWORK, 00269 HWLOC_OBJ_OSDEV_OPENFABRICS, 00271 HWLOC_OBJ_OSDEV_DMA 00273 } hwloc_obj_osdev_type_t; 00274 00292 int hwloc_compare_types (hwloc_obj_type_t type1, hwloc_obj_type_t type2) ; 00293 00294 enum hwloc_compare_types_e { 00295 HWLOC_TYPE_UNORDERED = INT_MAX 00296 }; 00297 00306 union hwloc_obj_attr_u; 00307 00309 struct hwloc_obj_memory_s { 00310 hwloc_uint64_t total_memory; 00311 hwloc_uint64_t local_memory; 00313 unsigned page_types_len; 00319 struct hwloc_obj_memory_page_type_s { 00320 hwloc_uint64_t size; 00321 hwloc_uint64_t count; 00322 } * page_types; 00323 }; 00324 00329 struct hwloc_obj { 00330 /* physical information */ 00331 hwloc_obj_type_t type; 00332 unsigned os_index; 00333 char *name; 00335 struct hwloc_obj_memory_s memory; 00337 union hwloc_obj_attr_u *attr; 00340 /* global position */ 00341 unsigned depth; 00342 unsigned logical_index; 00344 signed os_level; 00346 /* cousins are all objects of the same type (and depth) across the entire topology */ 00347 struct hwloc_obj *next_cousin; 00348 struct hwloc_obj *prev_cousin; 00350 /* children of the same parent are siblings, even if they may have different type and depth */ 00351 struct hwloc_obj *parent; 00352 unsigned sibling_rank; 00353 struct hwloc_obj *next_sibling; 00354 struct hwloc_obj *prev_sibling; 00356 /* children array below this object */ 00357 unsigned arity; 00358 struct hwloc_obj **children; 00359 struct hwloc_obj *first_child; 00360 struct hwloc_obj *last_child; 00362 /* misc */ 00363 void *userdata; 00365 /* cpusets and nodesets */ 00366 hwloc_cpuset_t cpuset; 00379 hwloc_cpuset_t complete_cpuset; 00390 hwloc_cpuset_t online_cpuset; 00398 hwloc_cpuset_t allowed_cpuset; 00409 hwloc_nodeset_t nodeset; 00426 hwloc_nodeset_t complete_nodeset; 00440 hwloc_nodeset_t allowed_nodeset; 00453 struct hwloc_distances_s **distances; 00454 unsigned distances_count; 00455 00456 struct hwloc_obj_info_s *infos; 00457 unsigned infos_count; 00458 }; 00462 typedef struct hwloc_obj * hwloc_obj_t; 00463 00465 union hwloc_obj_attr_u { 00467 struct hwloc_cache_attr_s { 00468 hwloc_uint64_t size; 00469 unsigned depth; 00470 unsigned linesize; 00471 int associativity; 00473 } cache; 00475 struct hwloc_group_attr_s { 00476 unsigned depth; 00477 } group; 00479 struct hwloc_pcidev_attr_s { 00480 unsigned short domain; 00481 unsigned char bus, dev, func; 00482 unsigned short class_id; 00483 unsigned short vendor_id, device_id, subvendor_id, subdevice_id; 00484 unsigned char revision; 00485 float linkspeed; /* in GB/s */ 00486 } pcidev; 00488 struct hwloc_bridge_attr_s { 00489 union { 00490 struct hwloc_pcidev_attr_s pci; 00491 } upstream; 00492 hwloc_obj_bridge_type_t upstream_type; 00493 union { 00494 struct { 00495 unsigned short domain; 00496 unsigned char secondary_bus, subordinate_bus; 00497 } pci; 00498 } downstream; 00499 hwloc_obj_bridge_type_t downstream_type; 00500 unsigned depth; 00501 } bridge; 00503 struct hwloc_osdev_attr_s { 00504 hwloc_obj_osdev_type_t type; 00505 } osdev; 00506 }; 00507 00522 struct hwloc_distances_s { 00523 unsigned relative_depth; 00525 unsigned nbobjs; 00530 float *latency; 00535 float latency_max; 00536 float latency_base; 00540 }; 00541 00543 struct hwloc_obj_info_s { 00544 char *name; 00545 char *value; 00546 }; 00547 00562 int hwloc_topology_init (hwloc_topology_t *topologyp); 00563 00576 int hwloc_topology_load(hwloc_topology_t topology); 00577 00582 void hwloc_topology_destroy (hwloc_topology_t topology); 00583 00595 void hwloc_topology_check(hwloc_topology_t topology); 00596 00631 int hwloc_topology_ignore_type(hwloc_topology_t topology, hwloc_obj_type_t type); 00632 00641 int hwloc_topology_ignore_type_keep_structure(hwloc_topology_t topology, hwloc_obj_type_t type); 00642 00650 int hwloc_topology_ignore_all_keep_structure(hwloc_topology_t topology); 00651 00656 enum hwloc_topology_flags_e { 00657 HWLOC_TOPOLOGY_FLAG_WHOLE_SYSTEM = (1<<0), 00666 HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM = (1<<1), 00686 /* \brief Detect PCI devices. 00687 * 00688 * By default, I/O devices are ignored. This flag enables I/O device 00689 * detection using the libpci backend. Only the common PCI devices (GPUs, 00690 * NICs, block devices, ...) and host bridges (objects that connect the host 00691 * objects to an I/O subsystem) will be added to the topology. 00692 * Uncommon devices and other bridges (such as PCI-to-PCI bridges) will be 00693 * ignored. 00694 */ 00695 HWLOC_TOPOLOGY_FLAG_IO_DEVICES = (1<<2), 00696 00697 /* \brief Detect PCI bridges. 00698 * 00699 * This flag should be combined with HWLOC_TOPOLOGY_FLAG_IO_DEVICES to enable 00700 * the detection of both common devices and of all useful bridges (bridges that 00701 * have at least one device behind them). 00702 */ 00703 HWLOC_TOPOLOGY_FLAG_IO_BRIDGES = (1<<3), 00704 00705 /* \brief Detect the whole PCI hierarchy. 00706 * 00707 * This flag enables detection of all I/O devices (even the uncommon ones) 00708 * and bridges (even those that have no device behind them) using the libpci 00709 * backend. 00710 */ 00711 HWLOC_TOPOLOGY_FLAG_WHOLE_IO = (1<<4) 00712 }; 00713 00718 int hwloc_topology_set_flags (hwloc_topology_t topology, unsigned long flags); 00719 00738 int hwloc_topology_set_fsroot(hwloc_topology_t restrict topology, const char * restrict fsroot_path); 00739 00754 int hwloc_topology_set_pid(hwloc_topology_t restrict topology, hwloc_pid_t pid); 00755 00778 int hwloc_topology_set_synthetic(hwloc_topology_t restrict topology, const char * restrict description); 00779 00796 int hwloc_topology_set_xml(hwloc_topology_t restrict topology, const char * restrict xmlpath); 00797 00811 int hwloc_topology_set_xmlbuffer(hwloc_topology_t restrict topology, const char * restrict buffer, int size); 00812 00828 int hwloc_topology_set_distance_matrix(hwloc_topology_t restrict topology, 00829 hwloc_obj_type_t type, unsigned nbobjs, 00830 unsigned *os_index, float *distances); 00831 00833 struct hwloc_topology_discovery_support { 00835 unsigned char pu; 00836 }; 00837 00839 struct hwloc_topology_cpubind_support { 00841 unsigned char set_thisproc_cpubind; 00843 unsigned char get_thisproc_cpubind; 00845 unsigned char set_proc_cpubind; 00847 unsigned char get_proc_cpubind; 00849 unsigned char set_thisthread_cpubind; 00851 unsigned char get_thisthread_cpubind; 00853 unsigned char set_thread_cpubind; 00855 unsigned char get_thread_cpubind; 00857 unsigned char get_thisproc_last_cpu_location; 00859 unsigned char get_proc_last_cpu_location; 00861 unsigned char get_thisthread_last_cpu_location; 00862 }; 00863 00865 struct hwloc_topology_membind_support { 00867 unsigned char set_thisproc_membind; 00869 unsigned char get_thisproc_membind; 00871 unsigned char set_proc_membind; 00873 unsigned char get_proc_membind; 00875 unsigned char set_thisthread_membind; 00877 unsigned char get_thisthread_membind; 00879 unsigned char set_area_membind; 00881 unsigned char get_area_membind; 00883 unsigned char alloc_membind; 00885 unsigned char firsttouch_membind; 00887 unsigned char bind_membind; 00889 unsigned char interleave_membind; 00891 unsigned char replicate_membind; 00893 unsigned char nexttouch_membind; 00894 00896 unsigned char migrate_membind; 00897 }; 00898 00905 struct hwloc_topology_support { 00906 struct hwloc_topology_discovery_support *discovery; 00907 struct hwloc_topology_cpubind_support *cpubind; 00908 struct hwloc_topology_membind_support *membind; 00909 }; 00910 00912 const struct hwloc_topology_support *hwloc_topology_get_support(hwloc_topology_t restrict topology); 00913 00928 int hwloc_topology_export_xml(hwloc_topology_t topology, const char *xmlpath); 00929 00939 int hwloc_topology_export_xmlbuffer(hwloc_topology_t topology, char **xmlbuffer, int *buflen); 00940 00942 void hwloc_free_xmlbuffer(hwloc_topology_t topology, char *xmlbuffer); 00943 00955 hwloc_obj_t hwloc_topology_insert_misc_object_by_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, const char *name); 00956 00969 hwloc_obj_t hwloc_topology_insert_misc_object_by_parent(hwloc_topology_t topology, hwloc_obj_t parent, const char *name); 00970 00972 enum hwloc_restrict_flags_e { 00973 HWLOC_RESTRICT_FLAG_ADAPT_DISTANCES = (1<<0), 00978 HWLOC_RESTRICT_FLAG_ADAPT_MISC = (1<<1), 00983 HWLOC_RESTRICT_FLAG_ADAPT_IO = (1<<2) 00988 }; 00989 01002 int hwloc_topology_restrict(hwloc_topology_t restrict topology, hwloc_const_cpuset_t cpuset, unsigned long flags); 01003 01021 unsigned hwloc_topology_get_depth(hwloc_topology_t restrict topology) ; 01022 01042 int hwloc_get_type_depth (hwloc_topology_t topology, hwloc_obj_type_t type); 01043 01044 enum hwloc_get_type_depth_e { 01045 HWLOC_TYPE_DEPTH_UNKNOWN = -1, 01046 HWLOC_TYPE_DEPTH_MULTIPLE = -2, 01047 HWLOC_TYPE_DEPTH_BRIDGE = -3, 01048 HWLOC_TYPE_DEPTH_PCI_DEVICE = -4, 01049 HWLOC_TYPE_DEPTH_OS_DEVICE = -5 01050 }; 01051 01056 hwloc_obj_type_t hwloc_get_depth_type (hwloc_topology_t topology, unsigned depth) ; 01057 01060 unsigned hwloc_get_nbobjs_by_depth (hwloc_topology_t topology, unsigned depth) ; 01061 01067 static inline int 01068 hwloc_get_nbobjs_by_type (hwloc_topology_t topology, hwloc_obj_type_t type) 01069 { 01070 int depth = hwloc_get_type_depth(topology, type); 01071 if (depth == HWLOC_TYPE_DEPTH_UNKNOWN) 01072 return 0; 01073 if (depth == HWLOC_TYPE_DEPTH_MULTIPLE) 01074 return -1; /* FIXME: agregate nbobjs from different levels? */ 01075 return hwloc_get_nbobjs_by_depth(topology, depth); 01076 } 01077 01085 int hwloc_topology_is_thissystem(hwloc_topology_t restrict topology) ; 01086 01101 hwloc_obj_t hwloc_get_obj_by_depth (hwloc_topology_t topology, unsigned depth, unsigned idx) ; 01102 01109 static inline hwloc_obj_t 01110 hwloc_get_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx) 01111 { 01112 int depth = hwloc_get_type_depth(topology, type); 01113 if (depth == HWLOC_TYPE_DEPTH_UNKNOWN) 01114 return NULL; 01115 if (depth == HWLOC_TYPE_DEPTH_MULTIPLE) 01116 return NULL; 01117 return hwloc_get_obj_by_depth(topology, depth, idx); 01118 } 01119 01129 const char * hwloc_obj_type_string (hwloc_obj_type_t type) ; 01130 01135 hwloc_obj_type_t hwloc_obj_type_of_string (const char * string) ; 01136 01147 int hwloc_obj_type_snprintf(char * restrict string, size_t size, hwloc_obj_t obj, 01148 int verbose); 01149 01161 int hwloc_obj_attr_snprintf(char * restrict string, size_t size, hwloc_obj_t obj, const char * restrict separator, 01162 int verbose); 01163 01184 int hwloc_obj_snprintf(char * restrict string, size_t size, 01185 hwloc_topology_t topology, hwloc_obj_t obj, 01186 const char * restrict indexprefix, int verbose); 01187 01195 int hwloc_obj_cpuset_snprintf(char * restrict str, size_t size, size_t nobj, const hwloc_obj_t * restrict objs); 01196 01203 static inline char * 01204 hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name) 01205 { 01206 unsigned i; 01207 for(i=0; i<obj->infos_count; i++) 01208 if (!strcmp(obj->infos[i].name, name)) 01209 return obj->infos[i].value; 01210 return NULL; 01211 } 01212 01220 void hwloc_obj_add_info(hwloc_obj_t obj, const char *name, const char *value); 01221 01279 typedef enum { 01280 HWLOC_CPUBIND_PROCESS = (1<<0), 01283 HWLOC_CPUBIND_THREAD = (1<<1), 01285 HWLOC_CPUBIND_STRICT = (1<<2), 01313 HWLOC_CPUBIND_NOMEMBIND = (1<<3) 01333 } hwloc_cpubind_flags_t; 01334 01340 int hwloc_set_cpubind(hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags); 01341 01347 int hwloc_get_cpubind(hwloc_topology_t topology, hwloc_cpuset_t set, int flags); 01348 01356 int hwloc_set_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_cpuset_t set, int flags); 01357 01369 int hwloc_get_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags); 01370 01371 #ifdef hwloc_thread_t 01372 01379 int hwloc_set_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_const_cpuset_t set, int flags); 01380 #endif 01381 01382 #ifdef hwloc_thread_t 01383 01390 int hwloc_get_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_cpuset_t set, int flags); 01391 #endif 01392 01400 int hwloc_get_last_cpu_location(hwloc_topology_t topology, hwloc_cpuset_t set, int flags); 01401 01418 int hwloc_get_proc_last_cpu_location(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags); 01419 01479 typedef enum { 01480 HWLOC_MEMBIND_DEFAULT = 0, 01482 HWLOC_MEMBIND_FIRSTTOUCH = 1, 01493 HWLOC_MEMBIND_BIND = 2, 01495 HWLOC_MEMBIND_INTERLEAVE = 3, 01510 HWLOC_MEMBIND_REPLICATE = 4, 01532 HWLOC_MEMBIND_NEXTTOUCH = 5, 01542 HWLOC_MEMBIND_MIXED = -1 01547 } hwloc_membind_policy_t; 01548 01560 typedef enum { 01561 HWLOC_MEMBIND_PROCESS = (1<<0), 01568 HWLOC_MEMBIND_THREAD = (1<<1), 01574 HWLOC_MEMBIND_STRICT = (1<<2), 01585 HWLOC_MEMBIND_MIGRATE = (1<<3), 01593 HWLOC_MEMBIND_NOCPUBIND = (1<<4) 01616 } hwloc_membind_flags_t; 01617 01630 int hwloc_set_membind_nodeset(hwloc_topology_t topology, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags); 01631 01645 int hwloc_set_membind(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags); 01646 01687 int hwloc_get_membind_nodeset(hwloc_topology_t topology, hwloc_nodeset_t nodeset, hwloc_membind_policy_t * policy, int flags); 01688 01734 int hwloc_get_membind(hwloc_topology_t topology, hwloc_cpuset_t cpuset, hwloc_membind_policy_t * policy, int flags); 01735 01745 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); 01746 01756 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); 01757 01794 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); 01795 01835 int hwloc_get_proc_membind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t cpuset, hwloc_membind_policy_t * policy, int flags); 01836 01843 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); 01844 01851 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); 01852 01875 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); 01876 01901 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); 01902 01910 void *hwloc_alloc(hwloc_topology_t topology, size_t len); 01911 01921 void *hwloc_alloc_membind_nodeset(hwloc_topology_t topology, size_t len, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags) ; 01922 01932 void *hwloc_alloc_membind(hwloc_topology_t topology, size_t len, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags) ; 01933 01937 int hwloc_free(hwloc_topology_t topology, void *addr, size_t len); 01938 01943 #ifdef __cplusplus 01944 } /* extern "C" */ 01945 #endif 01946 01947 01948 /* high-level helpers */ 01949 #include <hwloc/helper.h> 01950 01951 01952 #endif /* HWLOC_H */