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 */