OpenMPI  0.1.1
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  */
101  int dummy_value;
102 };
103 /** Unversioned convenience typedef; use this name in
104  frameworks/components to stay forward source-compatible */
106 /** Versioned convenience typedef */
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  */
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  */
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  */
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  */
251 
253  /**< Major number of the MCA. */
255  /**< Minor number of the MCA. */
257  /**< Release number of the MCA. */
258 
260  /**< String name of the framework that this component belongs to. */
262  /**< Major version number of the framework that this component
263  belongs to. */
265  /**< Minor version number of the framework that this component
266  belongs to. */
268  /**< Release version number of the framework that this component
269  belongs to. */
270 
272  /**< This comopnent's string name. */
274  /**< This component's major version number. */
276  /**< This component's minor version number. */
278  /**< This component's release version number. */
279 
281  /**< Method for opening this component. */
283  /**< Method for closing this component. */
285  /**< Method for querying this component. */
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 */
296 /** Versioned convenience typedef */
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  */
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 */
321 /** Versioned convenience typedef */
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 {
342  /**< Success. */
343  MCA_ERROR = -1,
344  /**< General error. */
346  /**< Out of resources; a fatal error. */
348  /**< Out of resources; try again later. */
350  /**< Equivalent to MPI_ERR_ARG error code. */
352  /**< Returned by functions or functionality that has not yet been
353  implemented */
355  /**< Returned by functionality that is not supported. */
356 
358  /**< Maximum error code. */
359 };
360 
361 #endif /* OPAL_MCA_H */
uint32_t param_field
Metadata parameter bit field filled in by the parameters defined above.
Definition: mca.h:310
Common type for all MCA components.
Definition: mca.h:250
#define MCA_BASE_MAX_COMPONENT_NAME_LEN
Maximum length of MCA component string names.
Definition: mca.h:240
Common type for all MCA modules.
Definition: mca.h:100
int mca_component_minor_version
This component's minor version number.
Definition: mca.h:275
mca_base_query_component_2_0_0_fn_t mca_query_component
Method for querying this component.
Definition: mca.h:284
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
int mca_type_minor_version
Minor version number of the framework that this component belongs to.
Definition: mca.h:264
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
int(* mca_base_register_component_params_2_0_0_fn_t)(void)
MCA component parameter registration function.
Definition: mca.h:230
Out of resources; a fatal error.
Definition: mca.h:345
int mca_release_version
Release number of the MCA.
Definition: mca.h:256
Equivalent to MPI_ERR_ARG error code.
Definition: mca.h:349
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
int(* mca_base_close_component_1_0_0_fn_t)(void)
MCA component close function.
Definition: mca.h:173
Returned by functions or functionality that has not yet been implemented.
Definition: mca.h:351
int mca_component_major_version
This component's major version number.
Definition: mca.h:273
mca_base_open_component_1_0_0_fn_t mca_open_component
Method for opening this component.
Definition: mca.h:280
Out of resources; try again later.
Definition: mca.h:347
int mca_type_release_version
Release version number of the framework that this component belongs to.
Definition: mca.h:267
mca_base_close_component_1_0_0_fn_t mca_close_component
Method for closing this component.
Definition: mca.h:282
int(* mca_base_open_component_1_0_0_fn_t)(void)
MCA component open function.
Definition: mca.h:150
Meta data for MCA v2.0.0 components.
Definition: mca.h:309
Success.
Definition: mca.h:341
#define MCA_BASE_MAX_TYPE_NAME_LEN
Maximum length of MCA framework string names.
Definition: mca.h:236
int mca_component_release_version
This component's release version number.
Definition: mca.h:277
Maximum error code.
Definition: mca.h:357
char mca_component_name[MCA_BASE_MAX_COMPONENT_NAME_LEN+1]
This comopnent's string name.
Definition: mca.h:271
int mca_major_version
Major number of the MCA.
Definition: mca.h:252
General error.
Definition: mca.h:343
char reserved[32]
Extra space to allow for expansion in the future without breaking older components.
Definition: mca.h:316
int mca_minor_version
Minor number of the MCA.
Definition: mca.h:254
Returned by functionality that is not supported.
Definition: mca.h:354
char reserved[32]
Extra space to allow for expansion in the future without breaking older components.
Definition: mca.h:291
int mca_type_major_version
Major version number of the framework that this component belongs to.
Definition: mca.h:261