1 /* -*- Mode: C; c-basic-offset:4 ; indent-tabs-mode:nil -*- */
2 /*
3 * Copyright (c) 2004-2008 The Trustees of Indiana University and Indiana
4 * University Research and Technology
5 * Corporation. All rights reserved.
6 * Copyright (c) 2004-2005 The University of Tennessee and The University
7 * of Tennessee Research Foundation. All rights
8 * reserved.
9 * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
10 * University of Stuttgart. All rights reserved.
11 * Copyright (c) 2004-2005 The Regents of the University of California.
12 * All rights reserved.
13 * Copyright (c) 2008-2012 Cisco Systems, Inc. All rights reserved.
14 * Copyright (c) 2015 Los Alamos National Security, LLC. All rights
15 * reserved.
16 * Copyright (c) 2016 Intel, Inc. All rights reserved.
17 * $COPYRIGHT$
18 *
19 * Additional copyrights may follow
20 *
21 * $HEADER$
22 */
23 /**
24 * @file
25 *
26 * Top-level interface for all pmix MCA components.
27 */
28
29 #ifndef PMIX_MCA_H
30 #define PMIX_MCA_H
31
32 #include <src/include/pmix_config.h>
33
34 /**
35 * Common type for all MCA modules.
36 *
37 * An instance of this type is always the first element in MCA
38 * modules, allowing the module to be associated with a
39 * particular version of a specific framework, and to publish its own
40 * name and version.
41 */
42 struct pmix_mca_base_module_2_0_0_t {
43 int dummy_value;
44 };
45 /** Unversioned convenience typedef; use this name in
46 frameworks/components to stay forward source-compatible */
47 typedef struct pmix_mca_base_module_2_0_0_t pmix_mca_base_module_t;
48 /** Versioned convenience typedef */
49 typedef struct pmix_mca_base_module_2_0_0_t pmix_mca_base_module_2_0_0_t;
50
51
52 /**
53 * MCA component open function.
54 *
55 * @retval PMIX_SUCCESS This component can be used in the process.
56 *
57 * @retval PMIX_ERR_NOT_AVAILABLE Silently ignore this component for
58 * the duration of the process (it may even be unloaded from the
59 * process).
60 *
61 * @retval anything_else The MCA base will print an error message
62 * ignore this component for the duration of the process (it may even
63 * be unloaded from the process).
64 *
65 * All MCA components can have an "open" function that is invoked once
66 * per process, when the component is located and loaded.
67 *
68 * This function should avoid registering MCA parameters (use the
69 * component "register" function for that; i.e.,
70 * mca_base_register_component_params_2_0_0_fn_t for that). Legacy
71 * components still register MCA params in their component "open"
72 * function, but their authors should update them to use the component
73 * "register" function.
74 *
75 * This function can also be used to allocate any resources necessary
76 * for the component (e.g., heap memory).
77 *
78 * This function should return PMIX_SUCCESS if it wishes to remain
79 * loaded in the process. Any other return value will cause the MCA
80 * base to unload the component. Although most components do not use
81 * this mechanism to force themselves to be unloaded (because if they
82 * are immediately unloaded, ompi_info will not display them), the
83 * mechanism is available should the need arise.
84 *
85 * If the component a) has no MCA parameters to register, b) no
86 * resources to allocate, and c) can always be used in a process
87 * (albiet perhaps not selected), it may provide NULL for this
88 * function. In this cause, the MCA will act as if it called the open
89 * function and it returned PMIX_SUCCESS.
90 */
91 typedef int (*pmix_mca_base_open_component_1_0_0_fn_t)(void);
92
93 /**
94 * MCA component close function.
95 *
96 * @retval PMIX_SUCCESS The component successfully shut down.
97 *
98 * @retval any_other_value Some error occurred, but is likely to be
99 * ignored.
100 *
101 * This function is invoked on a component after all of its modules
102 * have been finalized (according to the rules of its framework) and
103 * the component will never be used in the process again; the
104 * component may be unloaded from the process memory after the close
105 * function has been invoked.
106 *
107 * This function is typically used to release any resources still in
108 * use by the component.
109 *
110 * If the component has no resources to free, it may provide NULL for
111 * this function. In this case, the MCA will act as if it called the
112 * close function and it returned PMIX_SUCCESS.
113 */
114 typedef int (*pmix_mca_base_close_component_1_0_0_fn_t)(void);
115
116 /**
117 * MCA component query function.
118 *
119 * @retval PMIX_SUCCESS The component successfully queried.
120 *
121 * @retval any_other_value Some error occurred, but is likely to be
122 * ignored.
123 *
124 * @param module The module to be used if this component is selected.
125 *
126 * @param priority The priority of this component.
127 *
128 * This function is used by the mca_base_select function to find the
129 * highest priority component to select. Frameworks are free to
130 * implement their own query function, but must also implment their
131 * own select function as a result.
132 */
133 typedef int (*pmix_mca_base_query_component_2_0_0_fn_t)(pmix_mca_base_module_2_0_0_t **module, int *priority);
134
135 /**
136 * MCA component parameter registration function.
137 *
138 * @retval PMIX_SUCCESS This component successfully registered its
139 * parameters and can be used in this process.
140 * @retval PMIX_ERR_BAD_PARAM Indicates that the register function
141 * failed because an MCA parameter got an invalid/incorrect value.
142 *
143 * @retval anything_else The MCA will ignore this component for the
144 * duration of the process.
145 *
146 * If a component has a non-NULL parameter registration function, it
147 * will be invoked to register all MCA parameters associated with the
148 * component. This function is invoked *before* the component "open"
149 * function is invoked.
150 *
151 * The registration function should not allocate any resources that
152 * need to be freed (aside from registering MCA parameters).
153 * Specifically, strings that are passed to the MCA parameter
154 * registration functions are all internally copied; there's no need
155 * for the caller to keep them after registering a parameter. Hence,
156 * it is possible that the registration function will be the *only*
157 * function invoked on a component; component authors should take care
158 * that no resources are leaked in this case.
159 *
160 * This function should return PMIX_SUCCESS if it wishes to remain
161 * loaded in the process. Any other return value will cause the MCA
162 * base to unload the component. Although most components do not use
163 * this mechanism to force themselves to be unloaded (because if they
164 * are immediately unloaded, ompi_info will not display them), the
165 * mechanism is available should the need arise.
166 *
167 * Note that if the function returns PMIX_ERR_BAD_PARAM, it is
168 * possible (likely?) that the component didn't register all of its
169 * parameters. When this happens, ompi_info (and friends) will stop
170 * execution and print out all existing registered parameters from the
171 * entire framework (since ompi_info doesn't track individual
172 * component register failures). This allows a user to know exactly
173 * what value is incorrect, and from where it was set (e.g., via an
174 * MCA params file).
175 *
176 * If the component a) has no MCA parameters to register, b) no
177 * resources to allocate, and c) can always be used in a process
178 * (albiet perhaps not selected), it may provide NULL for this
179 * function. In this cause, the MCA will act as if it called the
180 * registration function and it returned PMIX_SUCCESS.
181 */
182 typedef int (*pmix_mca_base_register_component_params_2_0_0_fn_t)(void);
183
184
185 /**
186 * Maximum length of MCA project string names.
187 */
188 #define PMIX_MCA_BASE_MAX_PROJECT_NAME_LEN 15
189 /**
190 * Maximum length of MCA framework string names.
191 */
192 #define PMIX_MCA_BASE_MAX_TYPE_NAME_LEN 31
193 /**
194 * Maximum length of MCA component string names.
195 */
196 #define PMIX_MCA_BASE_MAX_COMPONENT_NAME_LEN 63
197
198 /**
199 * Common type for all MCA components.
200 *
201 * An instance of this type is always the first element in MCA
202 * components, allowing the component to be associated with a
203 * particular version of a specific framework, and to publish its own
204 * name and version.
205 */
206 struct pmix_mca_base_component_2_1_0_t {
207
208 int pmix_mca_major_version;
209 /**< Major number of the MCA. */
210 int pmix_mca_minor_version;
211 /**< Minor number of the MCA. */
212 int pmix_mca_release_version;
213 /**< Release number of the MCA. */
214
215 char pmix_mca_project_name[PMIX_MCA_BASE_MAX_PROJECT_NAME_LEN + 1];
216 /**< String name of the project that this component belongs to. */
217 int pmix_mca_project_major_version;
218 /**< Major version number of the project that this component
219 belongs to. */
220 int pmix_mca_project_minor_version;
221 /**< Minor version number of the project that this component
222 belongs to. */
223 int pmix_mca_project_release_version;
224 /**< Release version number of the project that this component
225 belongs to. */
226
227 char pmix_mca_type_name[PMIX_MCA_BASE_MAX_TYPE_NAME_LEN + 1];
228 /**< String name of the framework that this component belongs to. */
229 int pmix_mca_type_major_version;
230 /**< Major version number of the framework that this component
231 belongs to. */
232 int pmix_mca_type_minor_version;
233 /**< Minor version number of the framework that this component
234 belongs to. */
235 int pmix_mca_type_release_version;
236 /**< Release version number of the framework that this component
237 belongs to. */
238
239 char pmix_mca_component_name[PMIX_MCA_BASE_MAX_COMPONENT_NAME_LEN + 1];
240 /**< This comopnent's string name. */
241 int pmix_mca_component_major_version;
242 /**< This component's major version number. */
243 int pmix_mca_component_minor_version;
244 /**< This component's minor version number. */
245 int pmix_mca_component_release_version;
246 /**< This component's release version number. */
247
248 pmix_mca_base_open_component_1_0_0_fn_t pmix_mca_open_component;
249 /**< Method for opening this component. */
250 pmix_mca_base_close_component_1_0_0_fn_t pmix_mca_close_component;
251 /**< Method for closing this component. */
252 pmix_mca_base_query_component_2_0_0_fn_t pmix_mca_query_component;
253 /**< Method for querying this component. */
254 pmix_mca_base_register_component_params_2_0_0_fn_t pmix_mca_register_component_params;
255 /**< Method for registering the component's MCA parameters */
256
257 /** Extra space to allow for expansion in the future without
258 breaking older components. */
259 char reserved[32];
260 };
261 /** Unversioned convenience typedef; use this name in
262 frameworks/components to stay forward source-compatible */
263 typedef struct pmix_mca_base_component_2_1_0_t pmix_mca_base_component_t;
264 /** Versioned convenience typedef */
265 typedef struct pmix_mca_base_component_2_1_0_t pmix_mca_base_component_2_1_0_t;
266
267 /*
268 * Metadata Bit field parameters
269 */
270 #define PMIX_MCA_BASE_METADATA_PARAM_NONE (uint32_t)0x00 /**< No Metadata flags */
271 #define PMIX_MCA_BASE_METADATA_PARAM_CHECKPOINT (uint32_t)0x02 /**< Checkpoint enabled Component */
272 #define PMIX_MCA_BASE_METADATA_PARAM_DEBUG (uint32_t)0x04 /**< Debug enabled/only Component */
273
274 /**
275 * Meta data for MCA v2.0.0 components.
276 */
277 struct pmix_mca_base_component_data_2_0_0_t {
278 uint32_t param_field;
279 /**< Metadata parameter bit field filled in by the parameters
280 defined above */
281
282 /** Extra space to allow for expansion in the future without
283 breaking older components. */
284 char reserved[32];
285 };
286 /** Unversioned convenience typedef; use this name in
287 frameworks/components to stay forward source-compatible */
288 typedef struct pmix_mca_base_component_data_2_0_0_t pmix_mca_base_component_data_t;
289 /** Versioned convenience typedef */
290 typedef struct pmix_mca_base_component_data_2_0_0_t pmix_mca_base_component_data_2_0_0_t;
291
292 /**
293 * Macro for framework author convenience.
294 *
295 * This macro is used by frameworks defining their component types,
296 * indicating that they subscribe to the MCA version 2.0.0. See
297 * component header files (e.g., coll.h) for examples of its usage.
298 */
299 #define PMIX_MCA_BASE_VERSION_MAJOR 2
300 #define PMIX_MCA_BASE_VERSION_MINOR 1
301 #define PMIX_MCA_BASE_VERSION_RELEASE 0
302
303 #define PMIX_MCA_BASE_MAKE_VERSION(level, MAJOR, MINOR, RELEASE) \
304 .pmix_mca_## level ##_major_version = MAJOR, \
305 .pmix_mca_## level ##_minor_version = MINOR, \
306 .pmix_mca_## level ##_release_version = RELEASE
307
308
309 #define PMIX_MCA_BASE_VERSION_2_1_0(PROJECT, project_major, project_minor, project_release, TYPE, type_major, type_minor, type_release) \
310 .pmix_mca_major_version = PMIX_MCA_BASE_VERSION_MAJOR, \
311 .pmix_mca_minor_version = PMIX_MCA_BASE_VERSION_MINOR, \
312 .pmix_mca_release_version = PMIX_MCA_BASE_VERSION_RELEASE, \
313 .pmix_mca_project_name = PROJECT, \
314 PMIX_MCA_BASE_MAKE_VERSION(project, project_major, project_minor, project_release), \
315 .pmix_mca_type_name = TYPE, \
316 PMIX_MCA_BASE_MAKE_VERSION(type, type_major, type_minor, type_release)
317
318
319 #define PMIX_MCA_BASE_VERSION_1_0_0(type, type_major, type_minor, type_release) \
320 PMIX_MCA_BASE_VERSION_2_1_0("pmix", PMIX_MAJOR_VERSION, PMIX_MINOR_VERSION, \
321 PMIX_RELEASE_VERSION, type, type_major, type_minor, \
322 type_release)
323
324 #endif /* PMIX_MCA_H */