1 /* -*- Mode: C; c-basic-offset:4 ; indent-tabs-mode:nil -*- */
2 /*
3 * Copyright (c) 2012-2015 Los Alamos National Security, LLC. All rights
4 * reserved.
5 * Copyright (c) 2017 IBM Corporation. All rights reserved.
6 * Copyright (c) 2018 Triad National Security, LLC. All rights
7 * reserved.
8 * $COPYRIGHT$
9 *
10 * Additional copyrights may follow
11 *
12 * $HEADER$
13 */
14
15 #if !defined(OPAL_MCA_BASE_FRAMEWORK_H)
16 #define OPAL_MCA_BASE_FRAMEWORK_H
17
18 #include "opal/mca/mca.h"
19 #include "opal/class/opal_list.h"
20
21 /*
22 * Register and open flags
23 */
24 enum mca_base_register_flag_t {
25 MCA_BASE_REGISTER_DEFAULT = 0,
26 /** Register all components (ignore selection MCA variables) */
27 MCA_BASE_REGISTER_ALL = 1,
28 /** Do not register DSO components */
29 MCA_BASE_REGISTER_STATIC_ONLY = 2
30 };
31
32 typedef enum mca_base_register_flag_t mca_base_register_flag_t;
33
34 enum mca_base_open_flag_t {
35 MCA_BASE_OPEN_DEFAULT = 0,
36 /** Find components in mca_base_components_find. Used by
37 mca_base_framework_open() when NOREGISTER is specified
38 by the framework */
39 MCA_BASE_OPEN_FIND_COMPONENTS = 1,
40 /** Do not open DSO components */
41 MCA_BASE_OPEN_STATIC_ONLY = 2,
42 };
43
44 typedef enum mca_base_open_flag_t mca_base_open_flag_t;
45
46
47 /**
48 * Register the MCA framework parameters
49 *
50 * @param[in] flags Registration flags (see mca/base/base.h)
51 *
52 * @retval OPAL_SUCCESS on success
53 * @retval opal error code on failure
54 *
55 * This function registers all framework MCA parameters. This
56 * function should not call mca_base_framework_components_register().
57 *
58 * Frameworks are NOT required to provide this function. It
59 * may be NULL.
60 */
61 typedef int (*mca_base_framework_register_params_fn_t) (mca_base_register_flag_t flags);
62
63 /**
64 * Initialize the MCA framework
65 *
66 * @retval OPAL_SUCCESS Upon success
67 * @retval OPAL_ERROR Upon failure
68 *
69 * This must be the first function invoked in the MCA framework.
70 * It initializes the MCA framework, finds and opens components,
71 * populates the components list, etc.
72 *
73 * This function is invoked during opal_init() and during the
74 * initialization of the special case of the ompi_info command.
75 *
76 * This function fills in the components framework value, which
77 * is a list of all components that were successfully opened.
78 * This variable should \em only be used by other framework base
79 * functions or by ompi_info -- it is not considered a public
80 * interface member -- and is only mentioned here for completeness.
81 *
82 * Any resources allocated by this function must be freed
83 * in the framework close function.
84 *
85 * Frameworks are NOT required to provide this function. It may
86 * be NULL. If a framework does not provide an open function the
87 * default behavior of mca_base_framework_open() is to call
88 * mca_base_framework_components_open(). If a framework provides
89 * an open function it will need to call mca_base_framework_components_open()
90 * if it needs to open any components.
91 */
92 typedef int (*mca_base_framework_open_fn_t) (mca_base_open_flag_t flags);
93
94 /**
95 * Shut down the MCA framework.
96 *
97 * @retval OPAL_SUCCESS Always
98 *
99 * This function should shut downs everything in the MCA
100 * framework, and is called during opal_finalize() and the
101 * special case of the ompi_info command.
102 *
103 * It must be the last function invoked on the MCA framework.
104 *
105 * Frameworks are NOT required to provide this function. It may
106 * be NULL. If a framework does not provide a close function the
107 * default behavior of mca_base_framework_close() is to call
108 * mca_base_framework_components_close(). If a framework provide
109 * a close function it will need to call mca_base_framework_components_close()
110 * if any components were opened.
111 */
112 typedef int (*mca_base_framework_close_fn_t) (void);
113
114 typedef enum {
115 MCA_BASE_FRAMEWORK_FLAG_DEFAULT = 0,
116 /** Don't register any variables for this framework */
117 MCA_BASE_FRAMEWORK_FLAG_NOREGISTER = 1,
118 /** Internal. Don't set outside mca_base_framework.h */
119 MCA_BASE_FRAMEWORK_FLAG_REGISTERED = 2,
120 /** Framework does not have any DSO components */
121 MCA_BASE_FRAMEWORK_FLAG_NO_DSO = 4,
122 /** Internal. Don't set outside mca_base_framework.h */
123 MCA_BASE_FRAMEWORK_FLAG_OPEN = 8,
124 /**
125 * The upper 16 bits are reserved for project specific flags.
126 */
127 } mca_base_framework_flags_t;
128
129 typedef struct mca_base_framework_t {
130 /** Project name for this component (ex "opal") */
131 char *framework_project;
132 /** Framework name */
133 char *framework_name;
134 /** Description of this framework or NULL */
135 const char *framework_description;
136 /** Framework register function or NULL if the framework
137 and all its components have nothing to register */
138 mca_base_framework_register_params_fn_t framework_register;
139 /** Framework open function or NULL */
140 mca_base_framework_open_fn_t framework_open;
141 /** Framework close function or NULL */
142 mca_base_framework_close_fn_t framework_close;
143 /** Framework flags (future use) set to 0 */
144 mca_base_framework_flags_t framework_flags;
145 /** Framework open count */
146 int framework_refcnt;
147 /** List of static components */
148 const mca_base_component_t **framework_static_components;
149 /** Component selection. This will be registered with the MCA
150 variable system and should be either NULL (all components) or
151 a heap allocated, comma-delimited list of components. */
152 char *framework_selection;
153 /** Verbosity level (0-100) */
154 int framework_verbose;
155 /** Opal output for this framework (or -1) */
156 int framework_output;
157 /** List of selected components (filled in by mca_base_framework_register()
158 or mca_base_framework_open() */
159 opal_list_t framework_components;
160 /** List of components that failed to load */
161 opal_list_t framework_failed_components;
162 } mca_base_framework_t;
163
164
165 /**
166 * Register a framework with MCA.
167 *
168 * @param[in] framework framework to register
169 *
170 * @retval OPAL_SUCCESS Upon success
171 * @retval OPAL_ERROR Upon failure
172 *
173 * Call a framework's register function.
174 */
175 OPAL_DECLSPEC int mca_base_framework_register (mca_base_framework_t *framework,
176 mca_base_register_flag_t flags);
177
178 /**
179 * Register frameworks with MCA.
180 *
181 * @param[in] framework NULL-terminated list of frameworks to register
182 *
183 * @retval OPAL_SUCCESS Upon success
184 * @retval OPAL_ERROR Upon failure
185 *
186 * Call the MCA variable registration functions of each framework in the
187 * frameworks array.
188 */
189 OPAL_DECLSPEC int mca_base_framework_register_list (mca_base_framework_t **frameworks,
190 mca_base_register_flag_t flags);
191
192 /**
193 * Open a framework
194 *
195 * @param[in] framework framework to open
196 *
197 * @retval OPAL_SUCCESS Upon success
198 * @retval OPAL_ERROR Upon failure
199 *
200 * Call a framework's open function.
201 */
202 OPAL_DECLSPEC int mca_base_framework_open (mca_base_framework_t *framework,
203 mca_base_open_flag_t flags);
204
205 /**
206 * Open frameworks
207 *
208 * @param[in] frameworks NULL-terminated array of framework to open
209 *
210 * @retval OPAL_SUCCESS Upon success
211 * @retval OPAL_ERROR Upon failure
212 *
213 * Call the open function on multiple frameworks
214 */
215 OPAL_DECLSPEC int mca_base_framework_open_list (mca_base_framework_t **frameworks,
216 mca_base_open_flag_t flags);
217
218 /**
219 * Close a framework
220 *
221 * @param[in] framework framework to close
222 *
223 * @retval OPAL_SUCCESS Upon success
224 * @retval OPAL_ERROR Upon failure
225 *
226 * Call a framework's close function.
227 */
228 OPAL_DECLSPEC int mca_base_framework_close (mca_base_framework_t *framework);
229
230 /**
231 * Close frameworks
232 *
233 * @param[in] frameworks NULL-terminated array of framework to close
234 *
235 * @retval OPAL_SUCCESS Upon success
236 * @retval OPAL_ERROR Upon failure
237 *
238 * Call the close function on multiple frameworks
239 */
240 OPAL_DECLSPEC int mca_base_framework_close_list (mca_base_framework_t **frameworks);
241
242 /**
243 * Check if a framework is already registered
244 *
245 * @param[in] framework framework to query
246 *
247 * @retval true if the framework's mca variables are registered
248 * @retval false if not
249 */
250 OPAL_DECLSPEC bool mca_base_framework_is_registered (struct mca_base_framework_t *framework);
251
252
253 /**
254 * Check if a framework is already open
255 *
256 * @param[in] framework framework to query
257 *
258 * @retval true if the framework is open
259 * @retval false if not
260 */
261 OPAL_DECLSPEC bool mca_base_framework_is_open (struct mca_base_framework_t *framework);
262
263
264 /**
265 * Macro to declare an MCA framework
266 *
267 * Example:
268 * MCA_BASE_FRAMEWORK_DECLARE(opal, foo, NULL, opal_foo_open, opal_foo_close, MCA_BASE_FRAMEWORK_FLAG_LAZY)
269 */
270 #define MCA_BASE_FRAMEWORK_DECLARE(project, name, description, registerfn, openfn, closefn, static_components, flags) \
271 mca_base_framework_t project##_##name##_base_framework = { \
272 .framework_project = #project, \
273 .framework_name = #name, \
274 .framework_description = description, \
275 .framework_register = registerfn, \
276 .framework_open = openfn, \
277 .framework_close = closefn, \
278 .framework_flags = flags, \
279 .framework_refcnt = 0, \
280 .framework_static_components = static_components, \
281 .framework_selection = NULL, \
282 .framework_verbose = 0, \
283 .framework_output = -1}
284
285 #endif /* OPAL_MCA_BASE_FRAMEWORK_H */