OpenMPI  0.1.1
base.h
1 /*
2  * Copyright (c) 2011 Cisco Systems, Inc. All rights reserved.
3  * $COPYRIGHT$
4  *
5  * Additional copyrights may follow
6  *
7  * $HEADER$
8  */
9 
10 #ifndef OPAL_HWLOC_BASE_H
11 #define OPAL_HWLOC_BASE_H
12 
13 #include "opal_config.h"
14 
15 #include "opal/dss/dss_types.h"
17 
18 #include "opal/mca/hwloc/hwloc.h"
19 
20 /*
21  * Global functions for MCA overall hwloc open and close
22  */
23 
24 BEGIN_C_DECLS
25 
26 /**
27  * Initialize the hwloc MCA framework
28  *
29  * @retval OPAL_SUCCESS Upon success
30  * @retval OPAL_ERROR Upon failure
31  *
32  * This must be the first function invoked in the hwloc MCA
33  * framework. It initializes the hwloc MCA framework, finds
34  * and opens hwloc components, etc.
35  *
36  * This function is invoked during opal_init().
37  *
38  * This function fills in the internal global variable
39  * opal_hwloc_base_components_opened, which is a list of all
40  * hwloc components that were successfully opened. This
41  * variable should \em only be used by other hwloc base
42  * functions -- it is not considered a public interface member --
43  * and is only mentioned here for completeness.
44  *
45  * Note that this function does NOT fill the global variable
46  * opal_hwloc_topology, nor does it set the process-wide memory
47  * affinity policy. Filling opal_hwloc_topology via
48  * hwloc_topology_load() can be expensive (and/or serialized by the
49  * OS); it may not be desireable to call this function in every MPI
50  * process on a machine. Hence, it is the responsibility for an upper
51  * layer to both fill opal_hwloc_topology in some scalable way, as
52  * well as to invoke opal_hwloc_base_set_process_membind_policy()
53  * (after opal_hwloc_topology has been loaded) to set the process-wide
54  * memory affinity policy.
55  */
56 OPAL_DECLSPEC int opal_hwloc_base_open(void);
57 
58 /**
59  * Shut down the hwloc MCA framework.
60  *
61  * @retval OPAL_SUCCESS Always
62  *
63  * This function shuts down everything in the hwloc MCA
64  * framework, and is called during opal_finalize().
65  *
66  * It must be the last function invoked on the hwloc MCA
67  * framework.
68  */
69 OPAL_DECLSPEC int opal_hwloc_base_close(void);
70 
71 /**
72  * Debugging output stream
73  */
74 OPAL_DECLSPEC extern int opal_hwloc_base_output;
75 OPAL_DECLSPEC extern opal_list_t opal_hwloc_base_components;
76 OPAL_DECLSPEC extern bool opal_hwloc_base_inited;
77 OPAL_DECLSPEC extern bool opal_hwloc_topology_inited;
78 
79 #if OPAL_HAVE_HWLOC
80 OPAL_DECLSPEC extern char *opal_hwloc_base_slot_list;
81 OPAL_DECLSPEC extern char *opal_hwloc_base_cpu_set;
82 OPAL_DECLSPEC extern hwloc_cpuset_t opal_hwloc_base_given_cpus;
83 
84 /**
85  * Report a bind failure using the normal mechanisms if a component
86  * fails to bind memory -- according to the value of the
87  * hwloc_base_bind_failure_action MCA parameter.
88  */
89 OPAL_DECLSPEC int opal_hwloc_base_report_bind_failure(const char *file,
90  int line,
91  const char *msg,
92  int rc);
93 
94 OPAL_DECLSPEC opal_paffinity_locality_t opal_hwloc_base_get_relative_locality(hwloc_topology_t topo,
95  opal_hwloc_level_t level1,
96  unsigned int peer1,
97  opal_hwloc_level_t level2,
98  unsigned int peer2);
99 
100 OPAL_DECLSPEC void opal_hwloc_base_get_local_cpuset(void);
101 
102 /**
103  * Enum for what memory allocation policy we want for user allocations.
104  * MAP = memory allocation policy.
105  */
106 typedef enum {
107  OPAL_HWLOC_BASE_MAP_NONE,
108  OPAL_HWLOC_BASE_MAP_LOCAL_ONLY
109 } opal_hwloc_base_map_t;
110 
111 /**
112  * Global reflecting the MAP (set by MCA param).
113  */
114 OPAL_DECLSPEC extern opal_hwloc_base_map_t opal_hwloc_base_map;
115 
116 /**
117  * Enum for what to do if the hwloc framework tries to bind memory
118  * and fails. BFA = bind failure action.
119  */
120 typedef enum {
121  OPAL_HWLOC_BASE_MBFA_SILENT,
122  OPAL_HWLOC_BASE_MBFA_WARN,
123  OPAL_HWLOC_BASE_MBFA_ERROR
124 } opal_hwloc_base_mbfa_t;
125 
126 /**
127  * Global reflecting the BFA (set by MCA param).
128  */
129 OPAL_DECLSPEC extern opal_hwloc_base_mbfa_t opal_hwloc_base_mbfa;
130 
131 /* some critical helper functions */
132 OPAL_DECLSPEC int opal_hwloc_base_filter_cpus(hwloc_topology_t topo);
133 OPAL_DECLSPEC int opal_hwloc_base_get_topology(void);
134 OPAL_DECLSPEC void opal_hwloc_base_free_topology(hwloc_topology_t topo);
135 OPAL_DECLSPEC hwloc_cpuset_t opal_hwloc_base_get_available_cpus(hwloc_topology_t topo,
136  hwloc_obj_t obj);
137 OPAL_DECLSPEC unsigned int opal_hwloc_base_get_nbobjs_by_type(hwloc_topology_t topo,
138  hwloc_obj_type_t target,
139  unsigned cache_level,
140  opal_hwloc_resource_type_t rtype);
141 OPAL_DECLSPEC hwloc_obj_t opal_hwloc_base_get_obj_by_type(hwloc_topology_t topo,
142  hwloc_obj_type_t target,
143  unsigned cache_level,
144  unsigned int instance,
145  opal_hwloc_resource_type_t rtype);
146 OPAL_DECLSPEC unsigned int opal_hwloc_base_get_obj_idx(hwloc_topology_t topo,
147  hwloc_obj_t obj,
148  opal_hwloc_resource_type_t rtype);
149 OPAL_DECLSPEC void opal_hwloc_base_get_level_and_index(hwloc_cpuset_t cpus,
150  opal_hwloc_level_t *bind_level,
151  unsigned int *bind_idx);
152 OPAL_DECLSPEC unsigned int opal_hwloc_base_get_npus(hwloc_topology_t topo,
153  hwloc_obj_t target);
154 OPAL_DECLSPEC char* opal_hwloc_base_print_binding(opal_binding_policy_t binding);
155 OPAL_DECLSPEC char* opal_hwloc_base_print_locality(opal_paffinity_locality_t locality);
156 OPAL_DECLSPEC char* opal_hwloc_base_print_level(opal_hwloc_level_t level);
157 OPAL_DECLSPEC bool opal_hwloc_base_single_cpu(hwloc_cpuset_t cpuset);
158 
159 /**
160  * Provide a utility to parse a slot list against the local
161  * logical cpus, and produce a cpuset for the described binding
162  */
163 OPAL_DECLSPEC int opal_hwloc_base_slot_list_parse(const char *slot_str,
164  hwloc_topology_t topo,
165  hwloc_cpuset_t cpumask);
166 
167 /**
168  * Report a bind failure using the normal mechanisms if a component
169  * fails to bind memory -- according to the value of the
170  * hwloc_base_bind_failure_action MCA parameter.
171  */
172 OPAL_DECLSPEC int opal_hwloc_base_report_bind_failure(const char *file,
173  int line,
174  const char *msg,
175  int rc);
176 
177 /**
178  * This function sets the process-wide memory affinity policy
179  * according to opal_hwloc_base_map and opal_hwloc_base_mbfa. It needs
180  * to be a separate, standalone function (as opposed to being done
181  * during opal_hwloc_base_open()) because opal_hwloc_topology is not
182  * loaded by opal_hwloc_base_open(). Hence, an upper layer needs to
183  * invoke this function after opal_hwloc_topology has been loaded.
184  */
185 OPAL_DECLSPEC int opal_hwloc_base_set_process_membind_policy(void);
186 
187 /* datatype support */
188 OPAL_DECLSPEC int opal_hwloc_pack(opal_buffer_t *buffer, const void *src,
189  int32_t num_vals,
190  opal_data_type_t type);
191 OPAL_DECLSPEC int opal_hwloc_unpack(opal_buffer_t *buffer, void *dest,
192  int32_t *num_vals,
193  opal_data_type_t type);
194 OPAL_DECLSPEC int opal_hwloc_copy(hwloc_topology_t *dest,
195  hwloc_topology_t src,
196  opal_data_type_t type);
197 OPAL_DECLSPEC int opal_hwloc_compare(const hwloc_topology_t topo1,
198  const hwloc_topology_t topo2,
199  opal_data_type_t type);
200 OPAL_DECLSPEC int opal_hwloc_print(char **output, char *prefix,
201  hwloc_topology_t src,
202  opal_data_type_t type);
203 OPAL_DECLSPEC int opal_hwloc_size(size_t *size,
204  hwloc_topology_t src,
205  opal_data_type_t type);
206 OPAL_DECLSPEC void opal_hwloc_release(opal_dss_value_t *value);
207 
208 #endif
209 
210 END_C_DECLS
211 
212 #endif /* OPAL_HWLOC_BASE_H */
Structure of a topology object.
Definition: hwloc.h:329
Definition: dss_types.h:89
Buffer management types.
paffinity (processor affinity) framework component interface definitions.
Definition: opal_list.h:147
hwloc_obj_type_t
Type of topology object.
Definition: hwloc.h:164
Structure for holding a buffer to be used with the RML or OOB subsystems.
Definition: dss_types.h:159
Definition: private.h:56
Definition: cpuset.c:38