mca/pgpu/pgpu.h

0001 /* -*- Mode: C; c-basic-offset:4 ; indent-tabs-mode:nil -*- */
0002 /*
0003  * Copyright (c) 2007-2008 Cisco Systems, Inc.  All rights reserved.
0004  *
0005  * Copyright (c) 2015-2018 Research Organization for Information Science
0006  *                         and Technology (RIST). All rights reserved.
0007  * Copyright (c) 2018-2020 Intel, Inc.  All rights reserved.
0008  * Copyright (c) 2021-2022 Nanook Consulting.  All rights reserved.
0009  * $COPYRIGHT$
0010  *
0011  * Additional copyrights may follow
0012  *
0013  * $HEADER$
0014  */
0015
0016 /**
0017  * @file
0018  *
0019  * This interface is for use by PMIx servers to obtain GPU-related info
0020  * and to setup GPU support for applications prior to launch
0021  *
0022  * Available plugins may be defined at runtime via the typical MCA parameter
0023  * syntax.
0024  */
0025
0026 #ifndef PMIX_PGPU_H
0027 #define PMIX_PGPU_H
0028
0029 #include "src/include/pmix_config.h"
0030 #include "include/pmix.h"
0031
0032 #include "src/class/pmix_list.h"
0033 #include "src/include/pmix_globals.h"
0034 #include "src/mca/base/pmix_mca_base_framework.h"
0035 #include "src/mca/base/pmix_mca_base_var.h"
0036 #include "src/mca/mca.h"
0037 #include "src/server/pmix_server_ops.h"
0038
0039 BEGIN_C_DECLS
0040
0041 /******    MODULE DEFINITION    ******/
0042
0043 /**
0044  * Initialize the module. Returns an error if the module cannot
0045  * run, success if it can and wants to be used.
0046  */
0047 typedef pmix_status_t (*pmix_pgpu_base_module_init_fn_t)(void);
0048
0049 /**
0050  * Finalize the module. Tear down any allocated storage, disconnect
0051  * from any system support (e.g., LDAP server)
0052  */
0053 typedef void (*pmix_pgpu_base_module_fini_fn_t)(void);
0054
0055 /**
0056  * Provide an entry point for the PMIx_server_setup_application function
0057  */
0058 typedef pmix_status_t (*pmix_pgpu_base_module_allocate_fn_t)(pmix_namespace_t *nptr,
0059                                                              pmix_info_t info[], size_t ninfo,
0060                                                              pmix_list_t *ilist);
0061
0062 /**
0063  * Provide an entry point for the PMIx_server_setup_local_support function
0064  */
0065 typedef pmix_status_t (*pmix_pgpu_base_module_setup_local_fn_t)(pmix_nspace_env_cache_t *ns,
0066                                                                 pmix_info_t info[],
0067                                                                 size_t ninfo);
0068
0069 /**
0070  * Provide an opportunity to cleanup when a
0071  * local application process terminates
0072  */
0073 typedef void (*pmix_pgpu_base_module_child_finalized_fn_t)(pmix_proc_t *peer);
0074
0075 /**
0076  * Provide  an opportunity to cleanup after
0077  * all local clients for a given application have terminated
0078  */
0079 typedef void (*pmix_pgpu_base_module_local_app_finalized_fn_t)(pmix_namespace_t *nptr);
0080
0081 /**
0082  * Provide an opportunity for the components to cleanup any
0083  * resource allocations they may have assigned
0084  */
0085 typedef void (*pmix_pgpu_base_module_dregister_nspace_fn_t)(pmix_namespace_t *nptr);
0086
0087 /**
0088  * Request that the module report local inventory
0089  *
0090  * If the operation can be performed immediately, then the module should just
0091  * add the inventory (as pmix_kval_t's) to the provided object's list and
0092  * return PMIX_SUCCESS.
0093  *
0094  * If the module needs to perform some non-atomic operation
0095  * then it should shift to its own internal
0096  * thread, return PMIX_OPERATION_IN_PROGRESS, and execute the provided
0097  * callback function when the operation is completed.
0098  *
0099  * If there is no inventory to report, then just return PMIX_SUCCESS.
0100  *
0101  * If the module should be providing inventory but encounters an error,
0102  * then immediately return an error code if the error is immediately detected,
0103  * or execute the callback function with an error code if it is detected later.
0104  */
0105 typedef pmix_status_t (*pmix_pgpu_base_module_collect_inventory_fn_t)(pmix_info_t directives[], size_t ndirs,
0106                                                                       pmix_list_t *inventory);
0107
0108 /**
0109  * Deliver inventory for archiving by corresponding modules
0110  *
0111  * Modules are to search the provided inventory to identify
0112  * entries provided by their remote peers, and then store that
0113  * information in a manner that can be queried/retrieved by
0114  * the host RM and/or scheduler. If the operation can be
0115  * performed immediately (e.g., storing the information in
0116  * the local hash table), then the module should just perform
0117  * that operation and return the appropriate status.
0118  *
0119  * If the module needs to perform some non-atomic operation
0120  * (e.g., storing the information in a non-local DHT), then
0121  * it should shift to its own internal thread, return
0122  * PMIX_OPERATION_IN_PROGRESS, and execute the provided
0123  * callback function when the operation is completed.
0124  *
0125  * If there is no relevant inventory to archive, then the module
0126  * should just return PMIX_SUCCESS;
0127  */
0128 typedef pmix_status_t (*pmix_pgpu_base_module_deliver_inventory_fn_t)(pmix_info_t info[], size_t ninfo,
0129                                                                       pmix_info_t directives[], size_t ndirs);
0130
0131 /**
0132  * Base structure for a pgpu module. Each component should malloc a
0133  * copy of the module structure for each fabric plane they support.
0134  */
0135 typedef struct {
0136     char *name;
0137     /* provide a pointer to plane-specific metadata */
0138     void *plane;
0139     /* init/finalize */
0140     pmix_pgpu_base_module_init_fn_t init;
0141     pmix_pgpu_base_module_fini_fn_t finalize;
0142     pmix_pgpu_base_module_allocate_fn_t allocate;
0143     pmix_pgpu_base_module_setup_local_fn_t setup_local;
0144     pmix_pgpu_base_module_child_finalized_fn_t child_finalized;
0145     pmix_pgpu_base_module_local_app_finalized_fn_t local_app_finalized;
0146     pmix_pgpu_base_module_dregister_nspace_fn_t deregister_nspace;
0147     pmix_pgpu_base_module_collect_inventory_fn_t collect_inventory;
0148     pmix_pgpu_base_module_deliver_inventory_fn_t deliver_inventory;
0149 } pmix_pgpu_module_t;
0150
0151 /* define a few API versions of the functions - main difference is the
0152  * string nspace parameter instead of a pointer to pmix_namespace_t. This
0153  * is done as an optimization to avoid having every component look for
0154  * that pointer */
0155 typedef pmix_status_t (*pmix_pgpu_base_API_allocate_fn_t)(char *nspace, pmix_info_t info[],
0156                                                           size_t ninfo, pmix_list_t *ilist);
0157 typedef pmix_status_t (*pmix_pgpu_base_API_setup_local_fn_t)(char *nspace, pmix_info_t info[],
0158                                                              size_t ninfo);
0159 typedef pmix_status_t (*pmix_pgpu_base_API_setup_fork_fn_t)(const pmix_proc_t *peer, char ***env);
0160
0161 typedef void (*pmix_pgpu_base_API_deregister_nspace_fn_t)(char *nspace);
0162
0163 /**
0164  * Base structure for a pgpu API
0165  */
0166 typedef struct {
0167     char *name;
0168     /* init/finalize */
0169     pmix_pgpu_base_module_init_fn_t init;
0170     pmix_pgpu_base_module_fini_fn_t finalize;
0171     pmix_pgpu_base_API_allocate_fn_t allocate;
0172     pmix_pgpu_base_API_setup_local_fn_t setup_local;
0173     pmix_pgpu_base_API_setup_fork_fn_t setup_fork;
0174     pmix_pgpu_base_module_child_finalized_fn_t child_finalized;
0175     pmix_pgpu_base_module_local_app_finalized_fn_t local_app_finalized;
0176     pmix_pgpu_base_API_deregister_nspace_fn_t deregister_nspace;
0177     pmix_pgpu_base_module_collect_inventory_fn_t collect_inventory;
0178     pmix_pgpu_base_module_deliver_inventory_fn_t deliver_inventory;
0179 } pmix_pgpu_API_module_t;
0180
0181 /* declare the global APIs */
0182 PMIX_EXPORT extern pmix_pgpu_API_module_t pmix_pgpu;
0183
0184 /*
0185  * the standard component data structure
0186  */
0187 typedef pmix_mca_base_component_t pmix_pgpu_base_component_t;
0188
0189 /*
0190  * Macro for use in components that are of type pgpu
0191  */
0192 #define PMIX_PGPU_BASE_VERSION_1_0_0 PMIX_MCA_BASE_VERSION_1_0_0("pgpu", 1, 0, 0)
0193
0194 END_C_DECLS
0195
0196 #endif