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-2007 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) 2009 Cisco Systems, Inc. All rights reserved.
14 * Copyright (c) 2013-2015 Los Alamos National Security, LLC. All rights
15 * reserved.
16 * Copyright (c) 2015 Research Organization for Information Science
17 * and Technology (RIST). All rights reserved.
18 * Copyright (c) 2017 IBM Corporation. All rights reserved.
19 * Copyright (c) 2018 Triad National Security, LLC. All rights
20 * reserved.
21 * $COPYRIGHT$
22 *
23 * Additional copyrights may follow
24 *
25 * $HEADER$
26 */
27
28 #ifndef MCA_BASE_H
29 #define MCA_BASE_H
30
31 #include "opal_config.h"
32
33 #include "opal/class/opal_object.h"
34 #include "opal/class/opal_list.h"
35
36 /*
37 * These units are large enough to warrant their own .h files
38 */
39 #include "opal/mca/mca.h"
40 #include "opal/mca/base/mca_base_var.h"
41 #include "opal/mca/base/mca_base_framework.h"
42 #include "opal/util/cmd_line.h"
43 #include "opal/util/output.h"
44
45 BEGIN_C_DECLS
46
47 /*
48 * Structure for making plain lists of components
49 */
50 struct mca_base_component_list_item_t {
51 opal_list_item_t super;
52 const mca_base_component_t *cli_component;
53 };
54 typedef struct mca_base_component_list_item_t mca_base_component_list_item_t;
55 OPAL_DECLSPEC OBJ_CLASS_DECLARATION(mca_base_component_list_item_t);
56
57 /*
58 * Structure for making priority lists of components
59 */
60 struct mca_base_component_priority_list_item_t {
61 mca_base_component_list_item_t super;
62 int cpli_priority;
63 };
64 typedef struct mca_base_component_priority_list_item_t
65 mca_base_component_priority_list_item_t;
66
67 OPAL_DECLSPEC OBJ_CLASS_DECLARATION(mca_base_component_priority_list_item_t);
68
69 /*
70 * Public variables
71 */
72 OPAL_DECLSPEC extern char *mca_base_component_path;
73 OPAL_DECLSPEC extern bool mca_base_component_show_load_errors;
74 OPAL_DECLSPEC extern bool mca_base_component_track_load_errors;
75 OPAL_DECLSPEC extern bool mca_base_component_disable_dlopen;
76 OPAL_DECLSPEC extern char *mca_base_system_default_path;
77 OPAL_DECLSPEC extern char *mca_base_user_default_path;
78
79 /*
80 * Standard verbosity levels
81 */
82 enum {
83 /** total silence */
84 MCA_BASE_VERBOSE_NONE = -1,
85 /** only errors are printed */
86 MCA_BASE_VERBOSE_ERROR = 0,
87 /** emit messages about component selection, open, and unloading */
88 MCA_BASE_VERBOSE_COMPONENT = 10,
89 /** also emit warnings */
90 MCA_BASE_VERBOSE_WARN = 20,
91 /** also emit general, user-relevant information, such as rationale as to why certain choices
92 * or code paths were taken, information gleaned from probing the local system, etc. */
93 MCA_BASE_VERBOSE_INFO = 40,
94 /** also emit relevant tracing information (e.g., which functions were invoked /
95 * call stack entry/exit info) */
96 MCA_BASE_VERBOSE_TRACE = 60,
97 /** also emit Open MPI-developer-level (i.e,. highly detailed) information */
98 MCA_BASE_VERBOSE_DEBUG = 80,
99 /** also output anything else that might be useful */
100 MCA_BASE_VERBOSE_MAX = 100,
101 };
102
103 /*
104 * Public functions
105 */
106
107 /**
108 * First function called in the MCA.
109 *
110 * @return OPAL_SUCCESS Upon success
111 * @return OPAL_ERROR Upon failure
112 *
113 * This function starts up the entire MCA. It initializes a bunch
114 * of built-in MCA parameters, and initialized the MCA component
115 * repository.
116 *
117 * It must be the first MCA function invoked. It is normally
118 * invoked during the initialization stage and specifically
119 * invoked in the special case of the *_info command.
120 */
121 OPAL_DECLSPEC int mca_base_open(void);
122
123 /**
124 * Last function called in the MCA
125 *
126 * @return OPAL_SUCCESS Upon success
127 * @return OPAL_ERROR Upon failure
128 *
129 * This function closes down the entire MCA. It clears all MCA
130 * parameters and closes down the MCA component respository.
131 *
132 * It must be the last MCA function invoked. It is normally invoked
133 * during the finalize stage.
134 */
135 OPAL_DECLSPEC void mca_base_close(void);
136
137 /**
138 * A generic select function
139 *
140 */
141 OPAL_DECLSPEC int mca_base_select(const char *type_name, int output_id,
142 opal_list_t *components_available,
143 mca_base_module_t **best_module,
144 mca_base_component_t **best_component,
145 int *priority_out);
146
147 /**
148 * A function for component query functions to discover if they have
149 * been explicitly required to or requested to be selected.
150 *
151 * exclusive: If the specified component is the only component that is
152 * available for selection.
153 *
154 */
155 OPAL_DECLSPEC int mca_base_is_component_required(opal_list_t *components_available,
156 mca_base_component_t *component,
157 bool exclusive,
158 bool *is_required);
159
160 /* mca_base_cmd_line.c */
161
162 OPAL_DECLSPEC int mca_base_cmd_line_setup(opal_cmd_line_t *cmd);
163 OPAL_DECLSPEC int mca_base_cmd_line_process_args(opal_cmd_line_t *cmd,
164 char ***app_env,
165 char ***global_env);
166 OPAL_DECLSPEC void mca_base_cmd_line_wrap_args(char **args);
167
168 /* mca_base_component_compare.c */
169
170 OPAL_DECLSPEC int mca_base_component_compare_priority(mca_base_component_priority_list_item_t *a,
171 mca_base_component_priority_list_item_t *b);
172 OPAL_DECLSPEC int mca_base_component_compare(const mca_base_component_t *a,
173 const mca_base_component_t *b);
174 OPAL_DECLSPEC int mca_base_component_compatible(const mca_base_component_t *a,
175 const mca_base_component_t *b);
176 OPAL_DECLSPEC char * mca_base_component_to_string(const mca_base_component_t *a);
177
178 /* mca_base_component_find.c */
179
180 OPAL_DECLSPEC int mca_base_component_find (const char *directory, mca_base_framework_t *framework,
181 bool ignore_requested, bool open_dso_components);
182
183 /**
184 * Parse the requested component string and return an opal_argv of the requested
185 * (or not requested) components.
186 */
187 int mca_base_component_parse_requested (const char *requested, bool *include_mode,
188 char ***requested_component_names);
189
190 /**
191 * Filter a list of components based on a comma-delimted list of names and/or
192 * a set of meta-data flags.
193 *
194 * @param[in,out] components List of components to filter
195 * @param[in] output_id Output id to write to for error/warning/debug messages
196 * @param[in] filter_names Comma delimited list of components to use. Negate with ^.
197 * May be NULL.
198 * @param[in] filter_flags Metadata flags components are required to have set (CR ready)
199 *
200 * @returns OPAL_SUCCESS On success
201 * @returns OPAL_ERR_NOT_FOUND If some component in {filter_names} is not found in
202 * {components}. Does not apply to negated filters.
203 * @returns opal error code On other error.
204 *
205 * This function closes and releases any components that do not match the filter_name and
206 * filter flags.
207 */
208 OPAL_DECLSPEC int mca_base_components_filter (mca_base_framework_t *framework, uint32_t filter_flags);
209
210
211
212 /* Safely release some memory allocated by mca_base_component_find()
213 (i.e., is safe to call even if you never called
214 mca_base_component_find()). */
215 OPAL_DECLSPEC int mca_base_component_find_finalize(void);
216
217 /* mca_base_components_register.c */
218 OPAL_DECLSPEC int mca_base_framework_components_register (struct mca_base_framework_t *framework,
219 mca_base_register_flag_t flags);
220
221 /* mca_base_components_open.c */
222 OPAL_DECLSPEC int mca_base_framework_components_open (struct mca_base_framework_t *framework,
223 mca_base_open_flag_t flags);
224
225 OPAL_DECLSPEC int mca_base_components_open(const char *type_name, int output_id,
226 const mca_base_component_t **static_components,
227 opal_list_t *components_available,
228 bool open_dso_components);
229
230 /* mca_base_components_close.c */
231 /**
232 * Close and release a component.
233 *
234 * @param[in] component Component to close
235 * @param[in] output_id Output id for debugging output
236 *
237 * After calling this function the component may no longer be used.
238 */
239 OPAL_DECLSPEC void mca_base_component_close (const mca_base_component_t *component, int output_id);
240
241 /**
242 * Release a component without closing it.
243 * @param[in] component Component to close
244 * @param[in] output_id Output id for debugging output
245 *
246 * After calling this function the component may no longer be used.
247 */
248 void mca_base_component_unload (const mca_base_component_t *component, int output_id);
249
250 OPAL_DECLSPEC int mca_base_components_close(int output_id, opal_list_t *components_available,
251 const mca_base_component_t *skip);
252
253 OPAL_DECLSPEC int mca_base_framework_components_close (struct mca_base_framework_t *framework,
254 const mca_base_component_t *skip);
255
256 END_C_DECLS
257
258 #endif /* MCA_BASE_H */