root/opal/mca/pmix/pmix4x/pmix/src/mca/mca.h

/* [<][>][^][v][top][bottom][index][help] */

INCLUDED FROM


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

/* [<][>][^][v][top][bottom][index][help] */