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) 2016-2017 Intel, Inc. All rights reserved.
19 * $COPYRIGHT$
20 *
21 * Additional copyrights may follow
22 *
23 * $HEADER$
24 */
25
26 #ifndef PMIX_MCA_BASE_H
27 #define PMIX_MCA_BASE_H
28
29 #include <src/include/pmix_config.h>
30
31 #include "src/class/pmix_object.h"
32 #include "src/class/pmix_list.h"
33
34 /*
35 * These units are large enough to warrant their own .h files
36 */
37 #include "src/mca/mca.h"
38 #include "src/mca/base/pmix_mca_base_var.h"
39 #include "src/mca/base/pmix_mca_base_framework.h"
40 #include "src/util/cmd_line.h"
41 #include "src/util/output.h"
42
43 BEGIN_C_DECLS
44
45 /*
46 * Structure for making plain lists of components
47 */
48 struct pmix_mca_base_component_list_item_t {
49 pmix_list_item_t super;
50 const pmix_mca_base_component_t *cli_component;
51 };
52 typedef struct pmix_mca_base_component_list_item_t pmix_mca_base_component_list_item_t;
53 PMIX_EXPORT PMIX_CLASS_DECLARATION(pmix_mca_base_component_list_item_t);
54
55 /*
56 * Structure for making priority lists of components
57 */
58 struct pmix_mca_base_component_priority_list_item_t {
59 pmix_mca_base_component_list_item_t super;
60 int cpli_priority;
61 };
62 typedef struct pmix_mca_base_component_priority_list_item_t
63 pmix_mca_base_component_priority_list_item_t;
64
65 PMIX_EXPORT PMIX_CLASS_DECLARATION(pmix_mca_base_component_priority_list_item_t);
66
67 /*
68 * Public variables
69 */
70 PMIX_EXPORT extern char *pmix_mca_base_component_path;
71 PMIX_EXPORT extern bool pmix_mca_base_component_show_load_errors;
72 PMIX_EXPORT extern bool pmix_mca_base_component_track_load_errors;
73 PMIX_EXPORT extern bool pmix_mca_base_component_disable_dlopen;
74 PMIX_EXPORT extern char *pmix_mca_base_system_default_path;
75 PMIX_EXPORT extern char *pmix_mca_base_user_default_path;
76
77 /*
78 * Standard verbosity levels
79 */
80 enum {
81 /** total silence */
82 PMIX_MCA_BASE_VERBOSE_NONE = -1,
83 /** only errors are printed */
84 PMIX_MCA_BASE_VERBOSE_ERROR = 0,
85 /** emit messages about component selection, open, and unloading */
86 PMIX_MCA_BASE_VERBOSE_COMPONENT = 10,
87 /** also emit warnings */
88 PMIX_MCA_BASE_VERBOSE_WARN = 20,
89 /** also emit general, user-relevant information, such as rationale as to why certain choices
90 * or code paths were taken, information gleaned from probing the local system, etc. */
91 PMIX_MCA_BASE_VERBOSE_INFO = 40,
92 /** also emit relevant tracing information (e.g., which functions were invoked /
93 * call stack entry/exit info) */
94 PMIX_MCA_BASE_VERBOSE_TRACE = 60,
95 /** also emit PMIX-developer-level (i.e,. highly detailed) information */
96 PMIX_MCA_BASE_VERBOSE_DEBUG = 80,
97 /** also output anything else that might be useful */
98 PMIX_MCA_BASE_VERBOSE_MAX = 100,
99 };
100
101 /*
102 * Public functions
103 */
104
105 /**
106 * First function called in the MCA.
107 *
108 * @return PMIX_SUCCESS Upon success
109 * @return PMIX_ERROR Upon failure
110 *
111 * This function starts up the entire MCA. It initializes a bunch
112 * of built-in MCA parameters, and initialized the MCA component
113 * repository.
114 *
115 * It must be the first MCA function invoked. It is normally
116 * invoked during the initialization stage and specifically
117 * invoked in the special case of the *_info command.
118 */
119 PMIX_EXPORT int pmix_mca_base_open(void);
120
121 /**
122 * Last function called in the MCA
123 *
124 * @return PMIX_SUCCESS Upon success
125 * @return PMIX_ERROR Upon failure
126 *
127 * This function closes down the entire MCA. It clears all MCA
128 * parameters and closes down the MCA component respository.
129 *
130 * It must be the last MCA function invoked. It is normally invoked
131 * during the finalize stage.
132 */
133 PMIX_EXPORT int pmix_mca_base_close(void);
134
135 /**
136 * A generic select function
137 *
138 */
139 PMIX_EXPORT int pmix_mca_base_select(const char *type_name, int output_id,
140 pmix_list_t *components_available,
141 pmix_mca_base_module_t **best_module,
142 pmix_mca_base_component_t **best_component,
143 int *priority_out);
144
145 /**
146 * A function for component query functions to discover if they have
147 * been explicitly required to or requested to be selected.
148 *
149 * exclusive: If the specified component is the only component that is
150 * available for selection.
151 *
152 */
153 PMIX_EXPORT int pmix_mca_base_is_component_required(pmix_list_t *components_available,
154 pmix_mca_base_component_t *component,
155 bool exclusive,
156 bool *is_required);
157
158 /* mca_base_cmd_line.c */
159
160 PMIX_EXPORT int pmix_mca_base_cmd_line_setup(pmix_cmd_line_t *cmd);
161 PMIX_EXPORT int pmix_mca_base_cmd_line_process_args(pmix_cmd_line_t *cmd,
162 char ***app_env,
163 char ***global_env);
164 PMIX_EXPORT void pmix_mca_base_cmd_line_wrap_args(char **args);
165
166 /* pmix_mca_base_component_compare.c */
167
168 PMIX_EXPORT int pmix_mca_base_component_compare_priority(pmix_mca_base_component_priority_list_item_t *a,
169 pmix_mca_base_component_priority_list_item_t *b);
170 PMIX_EXPORT int pmix_mca_base_component_compare(const pmix_mca_base_component_t *a,
171 const pmix_mca_base_component_t *b);
172 PMIX_EXPORT int pmix_mca_base_component_compatible(const pmix_mca_base_component_t *a,
173 const pmix_mca_base_component_t *b);
174 PMIX_EXPORT char * pmix_mca_base_component_to_string(const pmix_mca_base_component_t *a);
175
176 /* pmix_mca_base_component_find.c */
177
178 PMIX_EXPORT int pmix_mca_base_component_find (const char *directory, pmix_mca_base_framework_t *framework,
179 bool ignore_requested, bool open_dso_components);
180
181 /**
182 * Parse the requested component string and return an pmix_argv of the requested
183 * (or not requested) components.
184 */
185 PMIX_EXPORT int pmix_mca_base_component_parse_requested (const char *requested, bool *include_mode,
186 char ***requested_component_names);
187
188 /**
189 * Filter a list of components based on a comma-delimted list of names and/or
190 * a set of meta-data flags.
191 *
192 * @param[in,out] components List of components to filter
193 * @param[in] output_id Output id to write to for error/warning/debug messages
194 * @param[in] filter_names Comma delimited list of components to use. Negate with ^.
195 * May be NULL.
196 * @param[in] filter_flags Metadata flags components are required to have set (CR ready)
197 *
198 * @returns PMIX_SUCCESS On success
199 * @returns PMIX_ERR_NOT_FOUND If some component in {filter_names} is not found in
200 * {components}. Does not apply to negated filters.
201 * @returns pmix error code On other error.
202 *
203 * This function closes and releases any components that do not match the filter_name and
204 * filter flags.
205 */
206 PMIX_EXPORT int pmix_mca_base_components_filter (pmix_mca_base_framework_t *framework, uint32_t filter_flags);
207
208
209
210 /* Safely release some memory allocated by pmix_mca_base_component_find()
211 (i.e., is safe to call even if you never called
212 pmix_mca_base_component_find()). */
213 PMIX_EXPORT int pmix_mca_base_component_find_finalize(void);
214
215 /* pmix_mca_base_components_register.c */
216 PMIX_EXPORT int pmix_mca_base_framework_components_register (struct pmix_mca_base_framework_t *framework,
217 pmix_mca_base_register_flag_t flags);
218
219 /* pmix_mca_base_components_open.c */
220 PMIX_EXPORT int pmix_mca_base_framework_components_open (struct pmix_mca_base_framework_t *framework,
221 pmix_mca_base_open_flag_t flags);
222
223 PMIX_EXPORT int pmix_mca_base_components_open(const char *type_name, int output_id,
224 const pmix_mca_base_component_t **static_components,
225 pmix_list_t *components_available,
226 bool open_dso_components);
227
228 /* pmix_mca_base_components_close.c */
229 /**
230 * Close and release a component.
231 *
232 * @param[in] component Component to close
233 * @param[in] output_id Output id for debugging output
234 *
235 * After calling this function the component may no longer be used.
236 */
237 PMIX_EXPORT void pmix_mca_base_component_close (const pmix_mca_base_component_t *component, int output_id);
238
239 /**
240 * Release a component without closing it.
241 * @param[in] component Component to close
242 * @param[in] output_id Output id for debugging output
243 *
244 * After calling this function the component may no longer be used.
245 */
246 PMIX_EXPORT void pmix_mca_base_component_unload (const pmix_mca_base_component_t *component, int output_id);
247
248 PMIX_EXPORT int pmix_mca_base_components_close(int output_id, pmix_list_t *components_available,
249 const pmix_mca_base_component_t *skip);
250
251 PMIX_EXPORT int pmix_mca_base_framework_components_close (struct pmix_mca_base_framework_t *framework,
252 const pmix_mca_base_component_t *skip);
253
254 END_C_DECLS
255
256 #endif /* MCA_BASE_H */