root/opal/mca/hwloc/base/base.h

INCLUDED FROM

   1 /*
   2  * Copyright (c) 2011-2017 Cisco Systems, Inc.  All rights reserved
   3  * Copyright (c) 2013-2017 Intel, Inc.  All rights reserved.
   4  * Copyright (c) 2017      Research Organization for Information Science
   5  *                         and Technology (RIST). All rights reserved.
   6  * $COPYRIGHT$
   7  *
   8  * Additional copyrights may follow
   9  *
  10  * $HEADER$
  11  */
  12 
  13 #ifndef OPAL_HWLOC_BASE_H
  14 #define OPAL_HWLOC_BASE_H
  15 
  16 #include "opal_config.h"
  17 
  18 #include "opal/dss/dss_types.h"
  19 
  20 #include "opal/mca/hwloc/hwloc-internal.h"
  21 
  22 #if HWLOC_API_VERSION < 0x20000
  23 #define HWLOC_OBJ_L3CACHE HWLOC_OBJ_CACHE
  24 #define HWLOC_OBJ_L2CACHE HWLOC_OBJ_CACHE
  25 #define HWLOC_OBJ_L1CACHE HWLOC_OBJ_CACHE
  26 #endif
  27 
  28 /*
  29  * Global functions for MCA overall hwloc open and close
  30  */
  31 
  32 BEGIN_C_DECLS
  33 
  34 /* ******************************************************************** */
  35 
  36 /**
  37  * Note that the open function does NOT fill the global variable
  38  * opal_hwloc_topology, nor does it set the process-wide memory
  39  * affinity policy.  Filling opal_hwloc_topology via
  40  * hwloc_topology_load() can be expensive (and/or serialized by the
  41  * OS); it may not be desireable to call this function in every MPI
  42  * process on a machine.  Hence, it is the responsibility for an upper
  43  * layer to both fill opal_hwloc_topology in some scalable way, as
  44  * well as to invoke opal_hwloc_base_set_process_membind_policy()
  45  * (after opal_hwloc_topology has been loaded) to set the process-wide
  46  * memory affinity policy.
  47  */
  48 
  49 /**
  50  * Debugging output stream
  51  */
  52 OPAL_DECLSPEC extern bool opal_hwloc_base_inited;
  53 OPAL_DECLSPEC extern bool opal_hwloc_topology_inited;
  54 
  55 OPAL_DECLSPEC extern mca_base_framework_t opal_hwloc_base_framework;
  56 
  57 /* we always must have some minimal locality support */
  58 #define OPAL_HWLOC_PRINT_MAX_SIZE   50
  59 #define OPAL_HWLOC_PRINT_NUM_BUFS   16
  60 typedef struct {
  61     char *buffers[OPAL_HWLOC_PRINT_NUM_BUFS];
  62     int cntr;
  63 } opal_hwloc_print_buffers_t;
  64 opal_hwloc_print_buffers_t *opal_hwloc_get_print_buffer(void);
  65 extern char* opal_hwloc_print_null;
  66 OPAL_DECLSPEC char* opal_hwloc_base_print_locality(opal_hwloc_locality_t locality);
  67 
  68 OPAL_DECLSPEC extern char *opal_hwloc_base_cpu_list;
  69 OPAL_DECLSPEC extern hwloc_cpuset_t opal_hwloc_base_given_cpus;
  70 OPAL_DECLSPEC extern char *opal_hwloc_base_topo_file;
  71 
  72 /* convenience macro for debugging */
  73 #define OPAL_HWLOC_SHOW_BINDING(n, v, t)                                \
  74     do {                                                                \
  75         char tmp1[1024];                                                \
  76         hwloc_cpuset_t bind;                                            \
  77         bind = opal_hwloc_alloc();                                      \
  78         if (hwloc_get_cpubind(t, bind,                                  \
  79                               HWLOC_CPUBIND_PROCESS) < 0) {             \
  80             opal_output_verbose(n, v,                                   \
  81                                 "CANNOT DETERMINE BINDING AT %s:%d",    \
  82                                 __FILE__, __LINE__);                    \
  83         } else {                                                        \
  84             opal_hwloc_base_cset2mapstr(tmp1, sizeof(tmp1), t, bind);   \
  85             opal_output_verbose(n, v,                                   \
  86                                 "BINDINGS AT %s:%d: %s",                \
  87                                 __FILE__, __LINE__, tmp1);              \
  88         }                                                               \
  89         hwloc_bitmap_free(bind);                                        \
  90     } while(0);
  91 
  92 #if HWLOC_API_VERSION < 0x20000
  93 #define OPAL_HWLOC_MAKE_OBJ_CACHE(level, obj, cache_level)              \
  94     do {                                                                \
  95         obj = HWLOC_OBJ_CACHE;                                          \
  96         cache_level = level;                                            \
  97     } while(0)
  98 #else
  99 #define OPAL_HWLOC_MAKE_OBJ_CACHE(level, obj, cache_level)              \
 100     do {                                                                \
 101         obj = HWLOC_OBJ_L##level##CACHE;                                \
 102         cache_level = 0;                                                \
 103     } while(0)
 104 #endif
 105 
 106 OPAL_DECLSPEC opal_hwloc_locality_t opal_hwloc_base_get_relative_locality(hwloc_topology_t topo,
 107                                                                           char *cpuset1, char *cpuset2);
 108 
 109 OPAL_DECLSPEC int opal_hwloc_base_set_binding_policy(opal_binding_policy_t *policy, char *spec);
 110 
 111 /**
 112  * Loads opal_hwloc_my_cpuset (global variable in
 113  * opal/mca/hwloc/hwloc-internal.h) for this process.  opal_hwloc_my_cpuset
 114  * will be loaded with this process' binding, or, if the process is
 115  * not bound, use the hwloc root object's (available and online)
 116  * cpuset.
 117  */
 118 OPAL_DECLSPEC void opal_hwloc_base_get_local_cpuset(void);
 119 
 120 struct opal_rmaps_numa_node_t {
 121     opal_list_item_t super;
 122     int index;
 123     float dist_from_closed;
 124 };
 125 typedef struct opal_rmaps_numa_node_t opal_rmaps_numa_node_t;
 126 OBJ_CLASS_DECLARATION(opal_rmaps_numa_node_t);
 127 
 128 /**
 129  * Enum for what memory allocation policy we want for user allocations.
 130  * MAP = memory allocation policy.
 131  */
 132 typedef enum {
 133     OPAL_HWLOC_BASE_MAP_NONE,
 134     OPAL_HWLOC_BASE_MAP_LOCAL_ONLY
 135 } opal_hwloc_base_map_t;
 136 
 137 /**
 138  * Global reflecting the MAP (set by MCA param).
 139  */
 140 OPAL_DECLSPEC extern opal_hwloc_base_map_t opal_hwloc_base_map;
 141 
 142 /**
 143  * Enum for what to do if the hwloc framework tries to bind memory
 144  * and fails.  BFA = bind failure action.
 145  */
 146 typedef enum {
 147     OPAL_HWLOC_BASE_MBFA_SILENT,
 148     OPAL_HWLOC_BASE_MBFA_WARN,
 149     OPAL_HWLOC_BASE_MBFA_ERROR
 150 } opal_hwloc_base_mbfa_t;
 151 
 152 /**
 153  * Global reflecting the BFA (set by MCA param).
 154  */
 155 OPAL_DECLSPEC extern opal_hwloc_base_mbfa_t opal_hwloc_base_mbfa;
 156 
 157 /**
 158  * Discover / load the hwloc topology (i.e., call hwloc_topology_init() and
 159  * hwloc_topology_load()).
 160  */
 161 OPAL_DECLSPEC int opal_hwloc_base_get_topology(void);
 162 
 163 /**
 164  * Set the hwloc topology to that from the given topo file
 165  */
 166 OPAL_DECLSPEC int opal_hwloc_base_set_topology(char *topofile);
 167 
 168 OPAL_DECLSPEC int opal_hwloc_base_filter_cpus(hwloc_topology_t topo);
 169 
 170 /**
 171  * Free the hwloc topology.
 172  */
 173 OPAL_DECLSPEC void opal_hwloc_base_free_topology(hwloc_topology_t topo);
 174 OPAL_DECLSPEC unsigned int opal_hwloc_base_get_nbobjs_by_type(hwloc_topology_t topo,
 175                                                               hwloc_obj_type_t target,
 176                                                               unsigned cache_level,
 177                                                               opal_hwloc_resource_type_t rtype);
 178 OPAL_DECLSPEC void opal_hwloc_base_clear_usage(hwloc_topology_t topo);
 179 
 180 OPAL_DECLSPEC hwloc_obj_t opal_hwloc_base_get_obj_by_type(hwloc_topology_t topo,
 181                                                           hwloc_obj_type_t target,
 182                                                           unsigned cache_level,
 183                                                           unsigned int instance,
 184                                                           opal_hwloc_resource_type_t rtype);
 185 OPAL_DECLSPEC unsigned int opal_hwloc_base_get_obj_idx(hwloc_topology_t topo,
 186                                                        hwloc_obj_t obj,
 187                                                        opal_hwloc_resource_type_t rtype);
 188 
 189 OPAL_DECLSPEC int opal_hwloc_get_sorted_numa_list(hwloc_topology_t topo,
 190                                     char* device_name,
 191                                     opal_list_t *sorted_list);
 192 
 193 /**
 194  * Get the number of pu's under a given hwloc object.
 195  */
 196 OPAL_DECLSPEC unsigned int opal_hwloc_base_get_npus(hwloc_topology_t topo,
 197                                                     hwloc_obj_t target);
 198 OPAL_DECLSPEC char* opal_hwloc_base_print_binding(opal_binding_policy_t binding);
 199 
 200 /**
 201  * Determine if there is a single cpu in a bitmap.
 202  */
 203 OPAL_DECLSPEC bool opal_hwloc_base_single_cpu(hwloc_cpuset_t cpuset);
 204 
 205 /**
 206  * Provide a utility to parse a slot list against the local
 207  * cpus of given type, and produce a cpuset for the described binding
 208  */
 209 OPAL_DECLSPEC int opal_hwloc_base_cpu_list_parse(const char *slot_str,
 210                                                   hwloc_topology_t topo,
 211                                                   opal_hwloc_resource_type_t rtype,
 212                                                   hwloc_cpuset_t cpumask);
 213 
 214 OPAL_DECLSPEC char* opal_hwloc_base_find_coprocessors(hwloc_topology_t topo);
 215 OPAL_DECLSPEC char* opal_hwloc_base_check_on_coprocessor(void);
 216 
 217 
 218 /**
 219  * Report a bind failure using the normal mechanisms if a component
 220  * fails to bind memory -- according to the value of the
 221  * hwloc_base_bind_failure_action MCA parameter.
 222  */
 223 OPAL_DECLSPEC int opal_hwloc_base_report_bind_failure(const char *file,
 224                                                       int line,
 225                                                       const char *msg,
 226                                                       int rc);
 227 
 228 /**
 229  * This function sets the process-wide memory affinity policy
 230  * according to opal_hwloc_base_map and opal_hwloc_base_mbfa.  It needs
 231  * to be a separate, standalone function (as opposed to being done
 232  * during opal_hwloc_base_open()) because opal_hwloc_topology is not
 233  * loaded by opal_hwloc_base_open().  Hence, an upper layer needs to
 234  * invoke this function after opal_hwloc_topology has been loaded.
 235  */
 236 OPAL_DECLSPEC int opal_hwloc_base_set_process_membind_policy(void);
 237 
 238 OPAL_DECLSPEC int opal_hwloc_base_membind(opal_hwloc_base_memory_segment_t *segs,
 239                                           size_t count, int node_id);
 240 
 241 OPAL_DECLSPEC int opal_hwloc_base_node_name_to_id(char *node_name, int *id);
 242 
 243 OPAL_DECLSPEC int opal_hwloc_base_memory_set(opal_hwloc_base_memory_segment_t *segments,
 244                                              size_t num_segments);
 245 
 246 /* datatype support */
 247 OPAL_DECLSPEC int opal_hwloc_pack(opal_buffer_t *buffer, const void *src,
 248                                   int32_t num_vals,
 249                                   opal_data_type_t type);
 250 OPAL_DECLSPEC int opal_hwloc_unpack(opal_buffer_t *buffer, void *dest,
 251                                     int32_t *num_vals,
 252                                     opal_data_type_t type);
 253 OPAL_DECLSPEC int opal_hwloc_copy(hwloc_topology_t *dest,
 254                                   hwloc_topology_t src,
 255                                   opal_data_type_t type);
 256 OPAL_DECLSPEC int opal_hwloc_compare(const hwloc_topology_t topo1,
 257                                      const hwloc_topology_t topo2,
 258                                      opal_data_type_t type);
 259 OPAL_DECLSPEC int opal_hwloc_print(char **output, char *prefix,
 260                                    hwloc_topology_t src,
 261                                    opal_data_type_t type);
 262 
 263 /**
 264  * Make a prettyprint string for a hwloc_cpuset_t (e.g., "socket
 265  * 2[core 3]").
 266  */
 267 OPAL_DECLSPEC int opal_hwloc_base_cset2str(char *str, int len,
 268                                            hwloc_topology_t topo,
 269                                            hwloc_cpuset_t cpuset);
 270 
 271 /**
 272  * Make a prettyprint string for a cset in a map format.
 273  * Example: [B./..]
 274  * Key:  [] - signifies socket
 275  *        / - divider between cores
 276  *        . - signifies PU a process not bound to
 277  *        B - signifies PU a process is bound to
 278  */
 279 OPAL_DECLSPEC int opal_hwloc_base_cset2mapstr(char *str, int len,
 280                                               hwloc_topology_t topo,
 281                                               hwloc_cpuset_t cpuset);
 282 
 283 /* get the hwloc object that corresponds to the given processor id  and type */
 284 OPAL_DECLSPEC hwloc_obj_t opal_hwloc_base_get_pu(hwloc_topology_t topo,
 285                                                  int lid,
 286                                                  opal_hwloc_resource_type_t rtype);
 287 
 288 /* get the topology "signature" so we can check for differences - caller
 289  * if responsible for freeing the returned string */
 290 OPAL_DECLSPEC char* opal_hwloc_base_get_topo_signature(hwloc_topology_t topo);
 291 
 292 
 293 /* get a string describing the locality of a given process */
 294 OPAL_DECLSPEC char* opal_hwloc_base_get_locality_string(hwloc_topology_t topo, char *bitmap);
 295 
 296 /* extract a location from the locality string */
 297 OPAL_DECLSPEC char* opal_hwloc_base_get_location(char *locality,
 298                                                  hwloc_obj_type_t type,
 299                                                  unsigned index);
 300 
 301 OPAL_DECLSPEC opal_hwloc_locality_t opal_hwloc_compute_relative_locality(char *loc1, char *loc2);
 302 
 303 OPAL_DECLSPEC int opal_hwloc_base_topology_export_xmlbuffer(hwloc_topology_t topology, char **xmlpath, int *buflen);
 304 
 305 OPAL_DECLSPEC int opal_hwloc_base_topology_set_flags (hwloc_topology_t topology, unsigned long flags, bool io);
 306 END_C_DECLS
 307 
 308 #endif /* OPAL_HWLOC_BASE_H */