OpenMPI 0.1.1

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

mca.h
Go to the documentation of this file.
1 /*
2 * Copyright (c) 2004-2008 The Trustees of Indiana University and Indiana
3 * University Research and Technology
4 * Corporation. All rights reserved.
5 * Copyright (c) 2004-2005 The University of Tennessee and The University
6 * of Tennessee Research Foundation. All rights
7 * reserved.
8 * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
9 * University of Stuttgart. All rights reserved.
10 * Copyright (c) 2004-2005 The Regents of the University of California.
11 * All rights reserved.
12 * Copyright (c) 2008 Cisco Systems, Inc. All rights reserved.
13 * $COPYRIGHT$
14 *
15 * Additional copyrights may follow
16 *
17 * $HEADER$
18 */
19 /**
20 * @file
21 *
22 * Top-level interface for \em all MCA components.
23 *
24 * Historical notes:
25 *
26 * Open MPI originally used a v1.0.0 of the MCA component structs, but
27 * did not have a version number in the struct name. If I recall
28 * correctly, this is because we simply didn't think through (or never
29 * envisioned) changing the MCA base component struct itself. Oops.
30 *
31 * We made some changes in the base struct in Open MPI v1.3, and
32 * decided the following at the same time:
33 *
34 * - Bump the MCA version number to 2.0.0 and add some "reserved"
35 * space at the end of the struct.
36 * - The major MCA version number is essentially tied to the space
37 * that the struct occupies; if we make future changes in the struct
38 * by just using some of the reserved space, it may be possible to
39 * just increment the minor version number (depending on the scope of
40 * the change). If we need to add more space to the struct, we'll
41 * increment the major version number.
42 * - The MCA base component struct now has a version number in it
43 * (starting with Open MPI v1.3, it is 2.0.0).
44 * - As was an unstated assumption in prior versions of Open MPI, the
45 * unversioned versions of struct names (both in the MCA base and in
46 * individual framework bases) are intended for components who want
47 * to be forward source-compatible. That is, the unversioned struct
48 * name always represents the most recent interface version. If you
49 * need to use an older version, you can explicitly use that older
50 * struct version name. Please note, however, the Open MPI
51 * developers may not generally provide older versions of framework
52 * interface structs unless they know if someone outside of the Open
53 * MPI community needs it.
54 *
55 * ***IF YOU NEED BACKWARDS SOURCE OR BINARY COMPATIBILITY, you must
56 * let us know!***
57 *
58 * - We are currently only aware of one external developer making Open
59 * MPI components for the v1.2 series. He already knows that there
60 * are major changes coming in the v1.3 series, and does not expect to
61 * be able to use his v1.2 DSO binaries in v1.3. As such, we are
62 * breaking backwards binary compatibility in v1.3: there is no
63 * possibility of loading an MCA v1.0 binary component in Open MPI
64 * v1.3 or beyond (source compatibility is much easier -- the binary
65 * "refuse to load MCA components <v2.0.0" policy is enforced in
66 * mca_base_component_find.c).
67 *
68 * ***IF YOU NEED BACKWARDS BINARY COMPATIBILITY, please let us
69 * know!***
70 *
71 * - Note that we decided that framework version numbers are *not*
72 * related to the MCA version number. It is permissible to bump the
73 * MCA version number and leave all the framework version numbers
74 * they same. Specifically: a component is uniquely identified by
75 * its (MCA version, framework version, component version) tuple.
76 * So a component that is simply compiled with two different MCA
77 * base versions is still considered "different" because the tuple
78 * first member is different.
79 * - Per the discussion above, we decided to have MCA v2.0 no longer
80 * load <v2.0.0 components, and therefore avoided the "how to upcast
81 * a component in memory" issue. After v2.0.0, it is slightly
82 * easier because the MCA component structs have "reserved" space at
83 * the end that may account for future version data fields.
84 */
85
86 #ifndef OPAL_MCA_H
87 #define OPAL_MCA_H
88
89 #include "opal_config.h"
90
91
92 /**
93 * Common type for all MCA modules.
94 *
95 * An instance of this type is always the first element in MCA
96 * modules, allowing the module to be associated with a
97 * particular version of a specific framework, and to publish its own
98 * name and version.
99 */
100 struct mca_base_module_2_0_0_t {
101 int dummy_value;
102 };
103 /** Unversioned convenience typedef; use this name in
104 frameworks/components to stay forward source-compatible */
105 typedef struct mca_base_module_2_0_0_t mca_base_module_t;
106 /** Versioned convenience typedef */
107 typedef struct mca_base_module_2_0_0_t mca_base_module_2_0_0_t;
108
109
110 /**
111 * MCA component open function.
112 *
113 * @retval MCA_SUCCESS (or OPAL_SUCCESS or ORTE_SUCCESS or
114 * OMPI_SUCCESS) This component can be used in the process.
115 *
116 * @retval OPAL_ERR_NOT_AVAILABLE Silently ignore this component for
117 * the duration of the process (it may even be unloaded from the
118 * process).
119 *
120 * @retval anything_else The MCA base will print an error message
121 * ignore this component for the duration of the process (it may even
122 * be unloaded from the process).
123 *
124 * All MCA components can have an "open" function that is invoked once
125 * per process, when the component is located and loaded. This function
126 * should register any MCA parameters (using
127 * mca_base_param_register_int() and mca_base_param_register_string())
128 * that will be used by the component. Parameter registrations should
129 * occur in this function because the ompi_info command can be used by
130 * users to display all available MCA parameters (and their default
131 * values). However, the ompi_info command \em only invokes this open
132 * function on all components (i.e., no other component API methods).
133 *
134 * This function can also be used to allocate any resources necessary
135 * for the component (e.g., heap memory).
136 *
137 * This function should return MCA_SUCCESS if it wishes to remain
138 * loaded in the process. Any other return value will cause the MCA
139 * base to unload the component. Although most components do not use
140 * this mechanism to force themselves to be unloaded (because if they
141 * are immediately unloaded, ompi_info will not display them), the
142 * mechanism is available should the need arise.
143 *
144 * If the component a) has no MCA parameters to register, b) no
145 * resources to allocate, and c) can always be used in a process
146 * (albiet perhaps not selected), it may provide NULL for this
147 * function. In this cause, the MCA will act as if it called the open
148 * function and it returned MCA_SUCCESS.
149 */
150 typedef int (*mca_base_open_component_1_0_0_fn_t)(void);
151
152 /**
153 * MCA component close function.
154 *
155 * @retval MCA_SUCCESS The component successfully shut down.
156 *
157 * @retval any_other_value Some error occurred, but is likely to be
158 * ignored.
159 *
160 * This function is invoked on a component after all of its modules
161 * have been finalized (according to the rules of its framework) and
162 * the component will never be used in the process again; the
163 * component may be unloaded from the process memory after the close
164 * function has been invoked.
165 *
166 * This function is typically used to release any resources still in
167 * use by the component.
168 *
169 * If the component has no resources to free, it may provide NULL for
170 * this function. In this case, the MCA will act as if it called the
171 * close function and it returned MCA_SUCCESS.
172 */
173 typedef int (*mca_base_close_component_1_0_0_fn_t)(void);
174
175 /**
176 * MCA component query function.
177 *
178 * @retval OPAL_SUCCESS The component successfully queried.
179 *
180 * @retval any_other_value Some error occurred, but is likely to be
181 * ignored.
182 *
183 * @param module The module to be used if this component is selected.
184 *
185 * @param priority The priority of this component.
186 *
187 * This function is used by the mca_base_select function to find the
188 * highest priority component to select. Frameworks are free to
189 * implement their own query function, but must also implment their
190 * own select function as a result.
191 */
192 typedef int (*mca_base_query_component_2_0_0_fn_t)(mca_base_module_2_0_0_t **module, int *priority);
193
194 /**
195 * MCA component parameter registration function.
196 *
197 * @retval MCA_SUCCESS This component successfully registered its
198 * parameters and can be used in this process.
199 *
200 * @retval anything_else The MCA will ignore this component for the
201 * duration of the process.
202 *
203 * If a component has a non-NULL parameter registration function, it
204 * will be invoked to register all MCA parameters associated with the
205 * component. This function is invoked *before* the component "open"
206 * function is invoked.
207 *
208 * The registration function should not allocate any resources that
209 * need to be freed (aside from registering MCA parameters).
210 * Specifically, strings that are passed to the MCA parameter
211 * registration functions are all internally copied; there's no need
212 * for the caller to keep them after registering a parameter. Hence,
213 * it is possible that the registration function will be the *only*
214 * function invoked on a component; component authors should take care
215 * that no resources are leaked in this case.
216 *
217 * This function should return MCA_SUCCESS if it wishes to remain
218 * loaded in the process. Any other return value will cause the MCA
219 * base to unload the component. Although most components do not use
220 * this mechanism to force themselves to be unloaded (because if they
221 * are immediately unloaded, ompi_info will not display them), the
222 * mechanism is available should the need arise.
223 *
224 * If the component a) has no MCA parameters to register, b) no
225 * resources to allocate, and c) can always be used in a process
226 * (albiet perhaps not selected), it may provide NULL for this
227 * function. In this cause, the MCA will act as if it called the
228 * registration function and it returned MCA_SUCCESS.
229 */
230 typedef int (*mca_base_register_component_params_2_0_0_fn_t)(void);
231
232
233 /**
234 * Maximum length of MCA framework string names.
235 */
236 #define MCA_BASE_MAX_TYPE_NAME_LEN 31
237 /**
238 * Maximum length of MCA component string names.
239 */
240 #define MCA_BASE_MAX_COMPONENT_NAME_LEN 63
241
242 /**
243 * Common type for all MCA components.
244 *
245 * An instance of this type is always the first element in MCA
246 * components, allowing the component to be associated with a
247 * particular version of a specific framework, and to publish its own
248 * name and version.
249 */
250 struct mca_base_component_2_0_0_t {
251
252 int mca_major_version;
253 /**< Major number of the MCA. */
254 int mca_minor_version;
255 /**< Minor number of the MCA. */
256 int mca_release_version;
257 /**< Release number of the MCA. */
258
259 char mca_type_name[MCA_BASE_MAX_TYPE_NAME_LEN + 1];
260 /**< String name of the framework that this component belongs to. */
261 int mca_type_major_version;
262 /**< Major version number of the framework that this component
263 belongs to. */
264 int mca_type_minor_version;
265 /**< Minor version number of the framework that this component
266 belongs to. */
267 int mca_type_release_version;
268 /**< Release version number of the framework that this component
269 belongs to. */
270
271 char mca_component_name[MCA_BASE_MAX_COMPONENT_NAME_LEN + 1];
272 /**< This comopnent's string name. */
273 int mca_component_major_version;
274 /**< This component's major version number. */
275 int mca_component_minor_version;
276 /**< This component's minor version number. */
277 int mca_component_release_version;
278 /**< This component's release version number. */
279
280 mca_base_open_component_1_0_0_fn_t mca_open_component;
281 /**< Method for opening this component. */
282 mca_base_close_component_1_0_0_fn_t mca_close_component;
283 /**< Method for closing this component. */
284 mca_base_query_component_2_0_0_fn_t mca_query_component;
285 /**< Method for querying this component. */
286 mca_base_register_component_params_2_0_0_fn_t mca_register_component_params;
287 /**< Method for registering the component's MCA parameters */
288
289 /** Extra space to allow for expansion in the future without
290 breaking older components. */
291 char reserved[32];
292 };
293 /** Unversioned convenience typedef; use this name in
294 frameworks/components to stay forward source-compatible */
295 typedef struct mca_base_component_2_0_0_t mca_base_component_t;
296 /** Versioned convenience typedef */
297 typedef struct mca_base_component_2_0_0_t mca_base_component_2_0_0_t;
298
299 /*
300 * Metadata Bit field parameters
301 */
302 #define MCA_BASE_METADATA_PARAM_NONE (uint32_t)0x00 /**< No Metadata flags */
303 #define MCA_BASE_METADATA_PARAM_CHECKPOINT (uint32_t)0x02 /**< Checkpoint enabled Component */
304 #define MCA_BASE_METADATA_PARAM_DEBUG (uint32_t)0x04 /**< Debug enabled/only Component */
305
306 /**
307 * Meta data for MCA v2.0.0 components.
308 */
309 struct mca_base_component_data_2_0_0_t {
310 uint32_t param_field;
311 /**< Metadata parameter bit field filled in by the parameters
312 defined above */
313
314 /** Extra space to allow for expansion in the future without
315 breaking older components. */
316 char reserved[32];
317 };
318 /** Unversioned convenience typedef; use this name in
319 frameworks/components to stay forward source-compatible */
320 typedef struct mca_base_component_data_2_0_0_t mca_base_component_data_t;
321 /** Versioned convenience typedef */
322 typedef struct mca_base_component_data_2_0_0_t mca_base_component_data_2_0_0_t;
323
324 /**
325 * Macro for framework author convenience.
326 *
327 * This macro is used by frameworks defining their component types,
328 * indicating that they subscribe to the MCA version 2.0.0. See
329 * component header files (e.g., coll.h) for examples of its usage.
330 */
331 #define MCA_BASE_VERSION_MAJOR 2
332 #define MCA_BASE_VERSION_MINOR 0
333 #define MCA_BASE_VERSION_RELEASE 0
334 #define MCA_BASE_VERSION_2_0_0 MCA_BASE_VERSION_MAJOR, MCA_BASE_VERSION_MINOR, MCA_BASE_VERSION_RELEASE
335
336
337 /**
338 * MCA return codes.
339 */
340 enum {
341 MCA_SUCCESS = 0,
342 /**< Success. */
343 MCA_ERROR = -1,
344 /**< General error. */
345 MCA_ERR_OUT_OF_RESOURCE = -2,
346 /**< Out of resources; a fatal error. */
347 MCA_ERR_TEMP_OUT_OF_RESOURCE = -3,
348 /**< Out of resources; try again later. */
349 MCA_ERR_BAD_PARAM = -5,
350 /**< Equivalent to MPI_ERR_ARG error code. */
351 MCA_ERR_NOT_IMPLEMENTED = -10,
352 /**< Returned by functions or functionality that has not yet been
353 implemented */
354 MCA_ERR_NOT_SUPPORTED = -11,
355 /**< Returned by functionality that is not supported. */
356
357 MCA_MAX_ERROR = -20
358 /**< Maximum error code. */
359 };
360
361 #endif /* OPAL_MCA_H */
mca_base_component_data_2_0_0_t::param_field
uint32_t param_field
Metadata parameter bit field filled in by the parameters defined above.
Definition: mca.h:310
mca_base_component_2_0_0_t
Common type for all MCA components.
Definition: mca.h:250
MCA_BASE_MAX_COMPONENT_NAME_LEN
#define MCA_BASE_MAX_COMPONENT_NAME_LEN
Maximum length of MCA component string names.
Definition: mca.h:240
mca_base_module_2_0_0_t
Common type for all MCA modules.
Definition: mca.h:100
mca_base_component_2_0_0_t::mca_component_minor_version
int mca_component_minor_version
This component's minor version number.
Definition: mca.h:275
mca_base_component_2_0_0_t::mca_query_component
mca_base_query_component_2_0_0_fn_t mca_query_component
Method for querying this component.
Definition: mca.h:284
mca_base_query_component_2_0_0_fn_t
int(* mca_base_query_component_2_0_0_fn_t)(mca_base_module_2_0_0_t **module, int *priority)
MCA component query function.
Definition: mca.h:192
mca_base_component_2_0_0_t::mca_type_minor_version
int mca_type_minor_version
Minor version number of the framework that this component belongs to.
Definition: mca.h:264
mca_base_component_2_0_0_t::mca_register_component_params
mca_base_register_component_params_2_0_0_fn_t mca_register_component_params
Method for registering the component's MCA parameters.
Definition: mca.h:286
mca_base_register_component_params_2_0_0_fn_t
int(* mca_base_register_component_params_2_0_0_fn_t)(void)
MCA component parameter registration function.
Definition: mca.h:230
MCA_ERR_OUT_OF_RESOURCE
Out of resources; a fatal error.
Definition: mca.h:345
mca_base_component_2_0_0_t::mca_release_version
int mca_release_version
Release number of the MCA.
Definition: mca.h:256
MCA_ERR_BAD_PARAM
Equivalent to MPI_ERR_ARG error code.
Definition: mca.h:349
mca_base_component_2_0_0_t::mca_type_name
char mca_type_name[MCA_BASE_MAX_TYPE_NAME_LEN+1]
String name of the framework that this component belongs to.
Definition: mca.h:259
mca_base_close_component_1_0_0_fn_t
int(* mca_base_close_component_1_0_0_fn_t)(void)
MCA component close function.
Definition: mca.h:173
MCA_ERR_NOT_IMPLEMENTED
Returned by functions or functionality that has not yet been implemented.
Definition: mca.h:351
mca_base_component_2_0_0_t::mca_component_major_version
int mca_component_major_version
This component's major version number.
Definition: mca.h:273
mca_base_component_2_0_0_t::mca_open_component
mca_base_open_component_1_0_0_fn_t mca_open_component
Method for opening this component.
Definition: mca.h:280
MCA_ERR_TEMP_OUT_OF_RESOURCE
Out of resources; try again later.
Definition: mca.h:347
mca_base_component_2_0_0_t::mca_type_release_version
int mca_type_release_version
Release version number of the framework that this component belongs to.
Definition: mca.h:267
mca_base_component_2_0_0_t::mca_close_component
mca_base_close_component_1_0_0_fn_t mca_close_component
Method for closing this component.
Definition: mca.h:282
mca_base_open_component_1_0_0_fn_t
int(* mca_base_open_component_1_0_0_fn_t)(void)
MCA component open function.
Definition: mca.h:150
mca_base_component_data_2_0_0_t
Meta data for MCA v2.0.0 components.
Definition: mca.h:309
MCA_SUCCESS
Success.
Definition: mca.h:341
MCA_BASE_MAX_TYPE_NAME_LEN
#define MCA_BASE_MAX_TYPE_NAME_LEN
Maximum length of MCA framework string names.
Definition: mca.h:236
mca_base_component_2_0_0_t::mca_component_release_version
int mca_component_release_version
This component's release version number.
Definition: mca.h:277
MCA_MAX_ERROR
Maximum error code.
Definition: mca.h:357
mca_base_component_2_0_0_t::mca_component_name
char mca_component_name[MCA_BASE_MAX_COMPONENT_NAME_LEN+1]
This comopnent's string name.
Definition: mca.h:271
mca_base_component_2_0_0_t::mca_major_version
int mca_major_version
Major number of the MCA.
Definition: mca.h:252
MCA_ERROR
General error.
Definition: mca.h:343
mca_base_component_data_2_0_0_t::reserved
char reserved[32]
Extra space to allow for expansion in the future without breaking older components.
Definition: mca.h:316
mca_base_component_2_0_0_t::mca_minor_version
int mca_minor_version
Minor number of the MCA.
Definition: mca.h:254
MCA_ERR_NOT_SUPPORTED
Returned by functionality that is not supported.
Definition: mca.h:354
mca_base_component_2_0_0_t::reserved
char reserved[32]
Extra space to allow for expansion in the future without breaking older components.
Definition: mca.h:291
mca_base_component_2_0_0_t::mca_type_major_version
int mca_type_major_version
Major version number of the framework that this component belongs to.
Definition: mca.h:261