Hardware Locality (hwloc)
1.4
|
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 0x00010400 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; 00346 unsigned logical_index; 00348 signed os_level; 00350 /* cousins are all objects of the same type (and depth) across the entire topology */ 00351 struct hwloc_obj *next_cousin; 00352 struct hwloc_obj *prev_cousin; 00354 /* children of the same parent are siblings, even if they may have different type and depth */ 00355 struct hwloc_obj *parent; 00356 unsigned sibling_rank; 00357 struct hwloc_obj *next_sibling; 00358 struct hwloc_obj *prev_sibling; 00360 /* children array below this object */ 00361 unsigned arity; 00362 struct hwloc_obj **children; 00363 struct hwloc_obj *first_child; 00364 struct hwloc_obj *last_child; 00366 /* misc */ 00367 void *userdata; 00369 /* cpusets and nodesets */ 00370 hwloc_cpuset_t cpuset; 00383 hwloc_cpuset_t complete_cpuset; 00394 hwloc_cpuset_t online_cpuset; 00402 hwloc_cpuset_t allowed_cpuset; 00413 hwloc_nodeset_t nodeset; 00430 hwloc_nodeset_t complete_nodeset; 00444 hwloc_nodeset_t allowed_nodeset; 00457 struct hwloc_distances_s **distances; 00458 unsigned distances_count; 00459 00460 struct hwloc_obj_info_s *infos; 00461 unsigned infos_count; 00463 int symmetric_subtree; 00466 }; 00470 typedef struct hwloc_obj * hwloc_obj_t; 00471 00473 union hwloc_obj_attr_u { 00475 struct hwloc_cache_attr_s { 00476 hwloc_uint64_t size; 00477 unsigned depth; 00478 unsigned linesize; 00479 int associativity; 00481 } cache; 00483 struct hwloc_group_attr_s { 00484 unsigned depth; 00485 } group; 00487 struct hwloc_pcidev_attr_s { 00488 unsigned short domain; 00489 unsigned char bus, dev, func; 00490 unsigned short class_id; 00491 unsigned short vendor_id, device_id, subvendor_id, subdevice_id; 00492 unsigned char revision; 00493 float linkspeed; /* in GB/s */ 00494 } pcidev; 00496 struct hwloc_bridge_attr_s { 00497 union { 00498 struct hwloc_pcidev_attr_s pci; 00499 } upstream; 00500 hwloc_obj_bridge_type_t upstream_type; 00501 union { 00502 struct { 00503 unsigned short domain; 00504 unsigned char secondary_bus, subordinate_bus; 00505 } pci; 00506 } downstream; 00507 hwloc_obj_bridge_type_t downstream_type; 00508 unsigned depth; 00509 } bridge; 00511 struct hwloc_osdev_attr_s { 00512 hwloc_obj_osdev_type_t type; 00513 } osdev; 00514 }; 00515 00530 struct hwloc_distances_s { 00531 unsigned relative_depth; 00533 unsigned nbobjs; 00538 float *latency; 00543 float latency_max; 00544 float latency_base; 00548 }; 00549 00551 struct hwloc_obj_info_s { 00552 char *name; 00553 char *value; 00554 }; 00555 00570 int hwloc_topology_init (hwloc_topology_t *topologyp); 00571 00584 int hwloc_topology_load(hwloc_topology_t topology); 00585 00590 void hwloc_topology_destroy (hwloc_topology_t topology); 00591 00603 void hwloc_topology_check(hwloc_topology_t topology); 00604 00639 int hwloc_topology_ignore_type(hwloc_topology_t topology, hwloc_obj_type_t type); 00640 00649 int hwloc_topology_ignore_type_keep_structure(hwloc_topology_t topology, hwloc_obj_type_t type); 00650 00658 int hwloc_topology_ignore_all_keep_structure(hwloc_topology_t topology); 00659 00664 enum hwloc_topology_flags_e { 00665 HWLOC_TOPOLOGY_FLAG_WHOLE_SYSTEM = (1<<0), 00674 HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM = (1<<1), 00694 /* \brief Detect PCI devices. 00695 * 00696 * By default, I/O devices are ignored. This flag enables I/O device 00697 * detection using the libpci backend. Only the common PCI devices (GPUs, 00698 * NICs, block devices, ...) and host bridges (objects that connect the host 00699 * objects to an I/O subsystem) will be added to the topology. 00700 * Uncommon devices and other bridges (such as PCI-to-PCI bridges) will be 00701 * ignored. 00702 */ 00703 HWLOC_TOPOLOGY_FLAG_IO_DEVICES = (1<<2), 00704 00705 /* \brief Detect PCI bridges. 00706 * 00707 * This flag should be combined with HWLOC_TOPOLOGY_FLAG_IO_DEVICES to enable 00708 * the detection of both common devices and of all useful bridges (bridges that 00709 * have at least one device behind them). 00710 */ 00711 HWLOC_TOPOLOGY_FLAG_IO_BRIDGES = (1<<3), 00712 00713 /* \brief Detect the whole PCI hierarchy. 00714 * 00715 * This flag enables detection of all I/O devices (even the uncommon ones) 00716 * and bridges (even those that have no device behind them) using the libpci 00717 * backend. 00718 */ 00719 HWLOC_TOPOLOGY_FLAG_WHOLE_IO = (1<<4) 00720 }; 00721 00726 int hwloc_topology_set_flags (hwloc_topology_t topology, unsigned long flags); 00727 00742 int hwloc_topology_set_pid(hwloc_topology_t restrict topology, hwloc_pid_t pid); 00743 00768 int hwloc_topology_set_fsroot(hwloc_topology_t restrict topology, const char * restrict fsroot_path); 00769 00794 int hwloc_topology_set_synthetic(hwloc_topology_t restrict topology, const char * restrict description); 00795 00817 int hwloc_topology_set_xml(hwloc_topology_t restrict topology, const char * restrict xmlpath); 00818 00840 int hwloc_topology_set_xmlbuffer(hwloc_topology_t restrict topology, const char * restrict buffer, int size); 00841 00851 int hwloc_topology_set_custom(hwloc_topology_t topology); 00852 00870 int hwloc_topology_set_distance_matrix(hwloc_topology_t restrict topology, 00871 hwloc_obj_type_t type, unsigned nbobjs, 00872 unsigned *os_index, float *distances); 00873 00875 struct hwloc_topology_discovery_support { 00877 unsigned char pu; 00878 }; 00879 00881 struct hwloc_topology_cpubind_support { 00883 unsigned char set_thisproc_cpubind; 00885 unsigned char get_thisproc_cpubind; 00887 unsigned char set_proc_cpubind; 00889 unsigned char get_proc_cpubind; 00891 unsigned char set_thisthread_cpubind; 00893 unsigned char get_thisthread_cpubind; 00895 unsigned char set_thread_cpubind; 00897 unsigned char get_thread_cpubind; 00899 unsigned char get_thisproc_last_cpu_location; 00901 unsigned char get_proc_last_cpu_location; 00903 unsigned char get_thisthread_last_cpu_location; 00904 }; 00905 00907 struct hwloc_topology_membind_support { 00909 unsigned char set_thisproc_membind; 00911 unsigned char get_thisproc_membind; 00913 unsigned char set_proc_membind; 00915 unsigned char get_proc_membind; 00917 unsigned char set_thisthread_membind; 00919 unsigned char get_thisthread_membind; 00921 unsigned char set_area_membind; 00923 unsigned char get_area_membind; 00925 unsigned char alloc_membind; 00927 unsigned char firsttouch_membind; 00929 unsigned char bind_membind; 00931 unsigned char interleave_membind; 00933 unsigned char replicate_membind; 00935 unsigned char nexttouch_membind; 00936 00938 unsigned char migrate_membind; 00939 }; 00940 00947 struct hwloc_topology_support { 00948 struct hwloc_topology_discovery_support *discovery; 00949 struct hwloc_topology_cpubind_support *cpubind; 00950 struct hwloc_topology_membind_support *membind; 00951 }; 00952 00954 const struct hwloc_topology_support *hwloc_topology_get_support(hwloc_topology_t restrict topology); 00955 00970 int hwloc_topology_export_xml(hwloc_topology_t topology, const char *xmlpath); 00971 00981 int hwloc_topology_export_xmlbuffer(hwloc_topology_t topology, char **xmlbuffer, int *buflen); 00982 00984 void hwloc_free_xmlbuffer(hwloc_topology_t topology, char *xmlbuffer); 00985 00997 hwloc_obj_t hwloc_topology_insert_misc_object_by_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, const char *name); 00998 01011 hwloc_obj_t hwloc_topology_insert_misc_object_by_parent(hwloc_topology_t topology, hwloc_obj_t parent, const char *name); 01012 01014 enum hwloc_restrict_flags_e { 01015 HWLOC_RESTRICT_FLAG_ADAPT_DISTANCES = (1<<0), 01020 HWLOC_RESTRICT_FLAG_ADAPT_MISC = (1<<1), 01025 HWLOC_RESTRICT_FLAG_ADAPT_IO = (1<<2) 01030 }; 01031 01044 int hwloc_topology_restrict(hwloc_topology_t restrict topology, hwloc_const_cpuset_t cpuset, unsigned long flags); 01045 01063 unsigned hwloc_topology_get_depth(hwloc_topology_t restrict topology) ; 01064 01084 int hwloc_get_type_depth (hwloc_topology_t topology, hwloc_obj_type_t type); 01085 01086 enum hwloc_get_type_depth_e { 01087 HWLOC_TYPE_DEPTH_UNKNOWN = -1, 01088 HWLOC_TYPE_DEPTH_MULTIPLE = -2, 01089 HWLOC_TYPE_DEPTH_BRIDGE = -3, 01090 HWLOC_TYPE_DEPTH_PCI_DEVICE = -4, 01091 HWLOC_TYPE_DEPTH_OS_DEVICE = -5 01092 }; 01093 01098 hwloc_obj_type_t hwloc_get_depth_type (hwloc_topology_t topology, unsigned depth) ; 01099 01102 unsigned hwloc_get_nbobjs_by_depth (hwloc_topology_t topology, unsigned depth) ; 01103 01109 static inline int 01110 hwloc_get_nbobjs_by_type (hwloc_topology_t topology, hwloc_obj_type_t type) 01111 { 01112 int depth = hwloc_get_type_depth(topology, type); 01113 if (depth == HWLOC_TYPE_DEPTH_UNKNOWN) 01114 return 0; 01115 if (depth == HWLOC_TYPE_DEPTH_MULTIPLE) 01116 return -1; /* FIXME: agregate nbobjs from different levels? */ 01117 return hwloc_get_nbobjs_by_depth(topology, depth); 01118 } 01119 01127 int hwloc_topology_is_thissystem(hwloc_topology_t restrict topology) ; 01128 01143 hwloc_obj_t hwloc_get_obj_by_depth (hwloc_topology_t topology, unsigned depth, unsigned idx) ; 01144 01151 static inline hwloc_obj_t 01152 hwloc_get_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx) 01153 { 01154 int depth = hwloc_get_type_depth(topology, type); 01155 if (depth == HWLOC_TYPE_DEPTH_UNKNOWN) 01156 return NULL; 01157 if (depth == HWLOC_TYPE_DEPTH_MULTIPLE) 01158 return NULL; 01159 return hwloc_get_obj_by_depth(topology, depth, idx); 01160 } 01161 01171 const char * hwloc_obj_type_string (hwloc_obj_type_t type) ; 01172 01177 hwloc_obj_type_t hwloc_obj_type_of_string (const char * string) ; 01178 01189 int hwloc_obj_type_snprintf(char * restrict string, size_t size, hwloc_obj_t obj, 01190 int verbose); 01191 01203 int hwloc_obj_attr_snprintf(char * restrict string, size_t size, hwloc_obj_t obj, const char * restrict separator, 01204 int verbose); 01205 01226 int hwloc_obj_snprintf(char * restrict string, size_t size, 01227 hwloc_topology_t topology, hwloc_obj_t obj, 01228 const char * restrict indexprefix, int verbose); 01229 01237 int hwloc_obj_cpuset_snprintf(char * restrict str, size_t size, size_t nobj, const hwloc_obj_t * restrict objs); 01238 01245 static inline char * 01246 hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name) 01247 { 01248 unsigned i; 01249 for(i=0; i<obj->infos_count; i++) 01250 if (!strcmp(obj->infos[i].name, name)) 01251 return obj->infos[i].value; 01252 return NULL; 01253 } 01254 01262 void hwloc_obj_add_info(hwloc_obj_t obj, const char *name, const char *value); 01263 01321 typedef enum { 01322 HWLOC_CPUBIND_PROCESS = (1<<0), 01325 HWLOC_CPUBIND_THREAD = (1<<1), 01327 HWLOC_CPUBIND_STRICT = (1<<2), 01355 HWLOC_CPUBIND_NOMEMBIND = (1<<3) 01375 } hwloc_cpubind_flags_t; 01376 01382 int hwloc_set_cpubind(hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags); 01383 01389 int hwloc_get_cpubind(hwloc_topology_t topology, hwloc_cpuset_t set, int flags); 01390 01398 int hwloc_set_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_cpuset_t set, int flags); 01399 01411 int hwloc_get_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags); 01412 01413 #ifdef hwloc_thread_t 01414 01421 int hwloc_set_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_const_cpuset_t set, int flags); 01422 #endif 01423 01424 #ifdef hwloc_thread_t 01425 01432 int hwloc_get_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_cpuset_t set, int flags); 01433 #endif 01434 01442 int hwloc_get_last_cpu_location(hwloc_topology_t topology, hwloc_cpuset_t set, int flags); 01443 01460 int hwloc_get_proc_last_cpu_location(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags); 01461 01521 typedef enum { 01522 HWLOC_MEMBIND_DEFAULT = 0, 01524 HWLOC_MEMBIND_FIRSTTOUCH = 1, 01535 HWLOC_MEMBIND_BIND = 2, 01537 HWLOC_MEMBIND_INTERLEAVE = 3, 01552 HWLOC_MEMBIND_REPLICATE = 4, 01574 HWLOC_MEMBIND_NEXTTOUCH = 5, 01584 HWLOC_MEMBIND_MIXED = -1 01589 } hwloc_membind_policy_t; 01590 01602 typedef enum { 01603 HWLOC_MEMBIND_PROCESS = (1<<0), 01610 HWLOC_MEMBIND_THREAD = (1<<1), 01616 HWLOC_MEMBIND_STRICT = (1<<2), 01627 HWLOC_MEMBIND_MIGRATE = (1<<3), 01635 HWLOC_MEMBIND_NOCPUBIND = (1<<4) 01658 } hwloc_membind_flags_t; 01659 01672 int hwloc_set_membind_nodeset(hwloc_topology_t topology, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags); 01673 01687 int hwloc_set_membind(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags); 01688 01729 int hwloc_get_membind_nodeset(hwloc_topology_t topology, hwloc_nodeset_t nodeset, hwloc_membind_policy_t * policy, int flags); 01730 01776 int hwloc_get_membind(hwloc_topology_t topology, hwloc_cpuset_t cpuset, hwloc_membind_policy_t * policy, int flags); 01777 01787 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); 01788 01798 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); 01799 01836 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); 01837 01877 int hwloc_get_proc_membind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t cpuset, hwloc_membind_policy_t * policy, int flags); 01878 01885 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); 01886 01893 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); 01894 01917 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); 01918 01943 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); 01944 01952 void *hwloc_alloc(hwloc_topology_t topology, size_t len); 01953 01963 void *hwloc_alloc_membind_nodeset(hwloc_topology_t topology, size_t len, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags) ; 01964 01974 void *hwloc_alloc_membind(hwloc_topology_t topology, size_t len, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags) ; 01975 01979 int hwloc_free(hwloc_topology_t topology, void *addr, size_t len); 01980 02011 int hwloc_custom_insert_topology(hwloc_topology_t newtopology, hwloc_obj_t newparent, hwloc_topology_t oldtopology, hwloc_obj_t oldroot); 02012 02029 hwloc_obj_t hwloc_custom_insert_group_object_by_parent(hwloc_topology_t topology, hwloc_obj_t parent, int groupdepth); 02030 02035 #ifdef __cplusplus 02036 } /* extern "C" */ 02037 #endif 02038 02039 02040 /* high-level helpers */ 02041 #include <hwloc/helper.h> 02042 02043 02044 #endif /* HWLOC_H */