1 // Copyright (c) 2017-2022, Lawrence Livermore National Security, LLC and other CEED contributors. 2 // All Rights Reserved. See the top-level LICENSE and NOTICE files for details. 3 // 4 // SPDX-License-Identifier: BSD-2-Clause 5 // 6 // This file is part of CEED: http://github.com/ceed 7 8 /// @file 9 /// Public header for backend components of libCEED 10 #ifndef _ceed_backend_h 11 #define _ceed_backend_h 12 13 #include <ceed/ceed.h> 14 #include <limits.h> 15 #include <stdbool.h> 16 17 #ifdef __cplusplus 18 # define CEED_INTERN extern "C" CEED_VISIBILITY(hidden) 19 #else 20 # define CEED_INTERN extern CEED_VISIBILITY(hidden) 21 #endif 22 23 #define CEED_UNUSED __attribute__((unused)) 24 25 #define CEED_MAX_RESOURCE_LEN 1024 26 #define CEED_MAX_BACKEND_PRIORITY UINT_MAX 27 #define CEED_ALIGN 64 28 #define CEED_COMPOSITE_MAX 16 29 #define CEED_FIELD_MAX 16 30 31 /** 32 @ingroup Ceed 33 This macro provides the ability to disable optimization flags for functions that 34 are sensitive to floting point optimizations. 35 **/ 36 #ifndef CeedPragmaOptimizeOff 37 # if defined(__clang__) 38 # define CeedPragmaOptimizeOff _Pragma("clang optimize off") 39 # elif defined(__GNUC__) 40 # define CeedPragmaOptimizeOff _Pragma("GCC push_options") _Pragma("GCC optimize 0") 41 # elif defined(__INTEL_COMPILER) || defined(__INTEL_LLVM_COMPILER) 42 # define CeedPragmaOptimizeOff _Pragma("optimize('', off)") 43 # else 44 # define CeedPragmaOptimizeOff 45 # endif 46 #endif 47 48 /** 49 @ingroup Ceed 50 This macro restores previously set optimization flags after CeedPragmaOptimizeOff. 51 **/ 52 #ifndef CeedPragmaOptimizeOn 53 # if defined(__clang__) 54 # define CeedPragmaOptimizeOn _Pragma("clang optimize on") 55 # elif defined(__GNUC__) 56 # define CeedPragmaOptimizeOn _Pragma("GCC pop_options") 57 # elif defined(__INTEL_COMPILER) || defined(__INTEL_LLVM_COMPILER) 58 # define CeedPragmaOptimizeOff _Pragma("optimize('', on)") 59 # else 60 # define CeedPragmaOptimizeOn 61 # endif 62 #endif 63 64 /// CEED_DEBUG_COLOR default value, forward CeedDebug* declarations & macros 65 #define CEED_DEBUG_COLOR_NONE 255 66 67 CEED_EXTERN void CeedDebugImpl256(const unsigned char, const char *, ...); 68 CEED_EXTERN bool CeedDebugFlag(const Ceed ceed); 69 CEED_EXTERN bool CeedDebugFlagEnv(void); 70 #define CeedDebug256(ceed, color, ...) \ 71 { if (CeedDebugFlag(ceed)) CeedDebugImpl256(color, ## __VA_ARGS__); } 72 #define CeedDebug(ceed, ...) CeedDebug256(ceed, (unsigned char)CEED_DEBUG_COLOR_NONE, ## __VA_ARGS__) 73 #define CeedDebugEnv256(color, ...) \ 74 { if (CeedDebugFlagEnv()) CeedDebugImpl256(color, ## __VA_ARGS__); } 75 #define CeedDebugEnv(...) CeedDebugEnv256((unsigned char)CEED_DEBUG_COLOR_NONE, ## __VA_ARGS__) 76 77 /// Handle for object handling TensorContraction 78 /// @ingroup CeedBasis 79 typedef struct CeedTensorContract_private *CeedTensorContract; 80 81 /// Handle for object handling assembled QFunction data 82 /// @ingroup CeedOperator 83 typedef struct CeedQFunctionAssemblyData_private *CeedQFunctionAssemblyData; 84 85 /* In the next 3 functions, p has to be the address of a pointer type, i.e. p 86 has to be a pointer to a pointer. */ 87 CEED_INTERN int CeedMallocArray(size_t n, size_t unit, void *p); 88 CEED_INTERN int CeedCallocArray(size_t n, size_t unit, void *p); 89 CEED_INTERN int CeedReallocArray(size_t n, size_t unit, void *p); 90 CEED_INTERN int CeedStringAllocCopy(const char *source, char **copy); 91 CEED_INTERN int CeedFree(void *p); 92 93 #define CeedChk(ierr) do { int ierr_ = ierr; if (ierr_) return ierr_; } while (0) 94 #define CeedChkBackend(ierr) do { int ierr_ = ierr; if (ierr_) { if (ierr_ > CEED_ERROR_SUCCESS) return CEED_ERROR_BACKEND; else return ierr_; } } while (0) 95 /* Note that CeedMalloc and CeedCalloc will, generally, return pointers with 96 different memory alignments: CeedMalloc returns pointers aligned at 97 CEED_ALIGN bytes, while CeedCalloc uses the alignment of calloc. */ 98 #define CeedMalloc(n, p) CeedMallocArray((n), sizeof(**(p)), p) 99 #define CeedCalloc(n, p) CeedCallocArray((n), sizeof(**(p)), p) 100 #define CeedRealloc(n, p) CeedReallocArray((n), sizeof(**(p)), p) 101 102 CEED_EXTERN int CeedRegister(const char *prefix, 103 int (*init)(const char *, Ceed), 104 unsigned int priority); 105 CEED_EXTERN int CeedRegisterImpl(const char *prefix, 106 int (*init)(const char *, Ceed), 107 unsigned int priority); 108 109 CEED_EXTERN int CeedIsDebug(Ceed ceed, bool *is_debug); 110 CEED_EXTERN int CeedGetParent(Ceed ceed, Ceed *parent); 111 CEED_EXTERN int CeedGetDelegate(Ceed ceed, Ceed *delegate); 112 CEED_EXTERN int CeedSetDelegate(Ceed ceed, Ceed delegate); 113 CEED_EXTERN int CeedGetObjectDelegate(Ceed ceed, Ceed *delegate, 114 const char *obj_name); 115 CEED_EXTERN int CeedSetObjectDelegate(Ceed ceed, Ceed delegate, 116 const char *obj_name); 117 CEED_EXTERN int CeedOperatorGetActiveBasis(CeedOperator op, 118 CeedBasis *active_basis); 119 CEED_EXTERN int CeedOperatorGetActiveElemRestriction(CeedOperator op, CeedElemRestriction *active_rstr); 120 CEED_EXTERN int CeedGetOperatorFallbackResource(Ceed ceed, 121 const char **resource); 122 CEED_EXTERN int CeedSetOperatorFallbackResource(Ceed ceed, 123 const char *resource); 124 CEED_EXTERN int CeedGetOperatorFallbackParentCeed(Ceed ceed, Ceed *parent); 125 CEED_EXTERN int CeedSetDeterministic(Ceed ceed, bool is_deterministic); 126 CEED_EXTERN int CeedSetBackendFunction(Ceed ceed, 127 const char *type, void *object, 128 const char *func_name, int (*f)()); 129 CEED_EXTERN int CeedGetData(Ceed ceed, void *data); 130 CEED_EXTERN int CeedSetData(Ceed ceed, void *data); 131 CEED_EXTERN int CeedReference(Ceed ceed); 132 133 CEED_EXTERN int CeedVectorHasValidArray(CeedVector vec, bool *has_valid_array); 134 CEED_EXTERN int CeedVectorHasBorrowedArrayOfType(CeedVector vec, CeedMemType mem_type, 135 bool *has_borrowed_array_of_type); 136 CEED_EXTERN int CeedVectorHasValidArray(CeedVector vec, bool *has_valid_array); 137 CEED_EXTERN int CeedVectorGetState(CeedVector vec, uint64_t *state); 138 CEED_EXTERN int CeedVectorAddReference(CeedVector vec); 139 CEED_EXTERN int CeedVectorGetData(CeedVector vec, void *data); 140 CEED_EXTERN int CeedVectorSetData(CeedVector vec, void *data); 141 CEED_EXTERN int CeedVectorReference(CeedVector vec); 142 143 CEED_EXTERN int CeedElemRestrictionGetStrides(CeedElemRestriction rstr, 144 CeedInt (*strides)[3]); 145 CEED_EXTERN int CeedElemRestrictionGetOffsets(CeedElemRestriction rstr, 146 CeedMemType mem_type, const CeedInt **offsets); 147 CEED_EXTERN int CeedElemRestrictionRestoreOffsets(CeedElemRestriction rstr, 148 const CeedInt **offsets); 149 CEED_EXTERN int CeedElemRestrictionIsStrided(CeedElemRestriction rstr, 150 bool *is_strided); 151 CEED_EXTERN int CeedElemRestrictionIsOriented(CeedElemRestriction rstr, 152 bool *is_oriented); 153 CEED_EXTERN int CeedElemRestrictionHasBackendStrides(CeedElemRestriction rstr, 154 bool *has_backend_strides); 155 CEED_EXTERN int CeedElemRestrictionGetELayout(CeedElemRestriction rstr, 156 CeedInt (*layout)[3]); 157 CEED_EXTERN int CeedElemRestrictionSetELayout(CeedElemRestriction rstr, 158 CeedInt layout[3]); 159 CEED_EXTERN int CeedElemRestrictionGetData(CeedElemRestriction rstr, 160 void *data); 161 CEED_EXTERN int CeedElemRestrictionSetData(CeedElemRestriction rstr, 162 void *data); 163 CEED_EXTERN int CeedElemRestrictionReference(CeedElemRestriction rstr); 164 165 /// Type of FE space; 166 /// @ingroup CeedBasis 167 typedef enum { 168 /// H1 FE space 169 CEED_FE_SPACE_H1 = 1, 170 /// H(div) FE space 171 CEED_FE_SPACE_HDIV = 2, 172 } CeedFESpace; 173 CEED_EXTERN const char *const CeedFESpaces[]; 174 175 CEED_EXTERN int CeedBasisGetCollocatedGrad(CeedBasis basis, 176 CeedScalar *colo_grad_1d); 177 CEED_EXTERN int CeedHouseholderApplyQ(CeedScalar *A, const CeedScalar *Q, 178 const CeedScalar *tau, CeedTransposeMode t_mode, 179 CeedInt m, CeedInt n, CeedInt k, 180 CeedInt row, CeedInt col); 181 CEED_EXTERN int CeedBasisIsTensor(CeedBasis basis, bool *is_tensor); 182 CEED_EXTERN int CeedBasisGetData(CeedBasis basis, void *data); 183 CEED_EXTERN int CeedBasisSetData(CeedBasis basis, void *data); 184 CEED_EXTERN int CeedBasisReference(CeedBasis basis); 185 186 CEED_EXTERN int CeedBasisGetTopologyDimension(CeedElemTopology topo, 187 CeedInt *dim); 188 189 CEED_EXTERN int CeedBasisGetTensorContract(CeedBasis basis, 190 CeedTensorContract *contract); 191 CEED_EXTERN int CeedBasisSetTensorContract(CeedBasis basis, 192 CeedTensorContract contract); 193 CEED_EXTERN int CeedTensorContractCreate(Ceed ceed, CeedBasis basis, 194 CeedTensorContract *contract); 195 CEED_EXTERN int CeedTensorContractApply(CeedTensorContract contract, CeedInt A, 196 CeedInt B, CeedInt C, CeedInt J, 197 const CeedScalar *__restrict__ t, 198 CeedTransposeMode t_mode, 199 const CeedInt Add, 200 const CeedScalar *__restrict__ u, 201 CeedScalar *__restrict__ v); 202 CEED_EXTERN int CeedTensorContractGetCeed(CeedTensorContract contract, 203 Ceed *ceed); 204 CEED_EXTERN int CeedTensorContractGetData(CeedTensorContract contract, 205 void *data); 206 CEED_EXTERN int CeedTensorContractSetData(CeedTensorContract contract, 207 void *data); 208 CEED_EXTERN int CeedTensorContractReference(CeedTensorContract contract); 209 CEED_EXTERN int CeedTensorContractDestroy(CeedTensorContract *contract); 210 211 CEED_EXTERN int CeedQFunctionRegister(const char *, const char *, CeedInt, 212 CeedQFunctionUser, int (*init)(Ceed, const char *, CeedQFunction)); 213 CEED_EXTERN int CeedQFunctionSetFortranStatus(CeedQFunction qf, bool status); 214 CEED_EXTERN int CeedQFunctionGetVectorLength(CeedQFunction qf, 215 CeedInt *vec_length); 216 CEED_EXTERN int CeedQFunctionGetNumArgs(CeedQFunction qf, 217 CeedInt *num_input_fields, 218 CeedInt *num_output_fields); 219 CEED_EXTERN int CeedQFunctionGetKernelName(CeedQFunction qf, char **kernel_name); 220 CEED_EXTERN int CeedQFunctionGetSourcePath(CeedQFunction qf, char **source_path); 221 CEED_EXTERN int CeedQFunctionLoadSourceToBuffer(CeedQFunction qf, char **source_buffer); 222 CEED_EXTERN int CeedQFunctionGetUserFunction(CeedQFunction qf, 223 CeedQFunctionUser *f); 224 CEED_EXTERN int CeedQFunctionGetContext(CeedQFunction qf, 225 CeedQFunctionContext *ctx); 226 CEED_EXTERN int CeedQFunctionGetContextData(CeedQFunction qf, CeedMemType mem_type, void *data); 227 CEED_EXTERN int CeedQFunctionRestoreContextData(CeedQFunction qf, void *data); 228 CEED_EXTERN int CeedQFunctionGetInnerContext(CeedQFunction qf, 229 CeedQFunctionContext *ctx); 230 CEED_EXTERN int CeedQFunctionGetInnerContextData(CeedQFunction qf, CeedMemType mem_type, void *data); 231 CEED_EXTERN int CeedQFunctionRestoreInnerContextData(CeedQFunction qf, void *data); 232 CEED_EXTERN int CeedQFunctionIsIdentity(CeedQFunction qf, bool *is_identity); 233 CEED_EXTERN int CeedQFunctionIsContextWritable(CeedQFunction qf, bool *is_writable); 234 CEED_EXTERN int CeedQFunctionGetData(CeedQFunction qf, void *data); 235 CEED_EXTERN int CeedQFunctionSetData(CeedQFunction qf, void *data); 236 CEED_EXTERN int CeedQFunctionReference(CeedQFunction qf); 237 238 CEED_EXTERN int CeedQFunctionContextGetCeed(CeedQFunctionContext ctx, 239 Ceed *ceed); 240 CEED_EXTERN int CeedQFunctionContextHasValidData(CeedQFunctionContext ctx, 241 bool *has_valid_data); 242 CEED_EXTERN int CeedQFunctionContextHasBorrowedDataOfType(CeedQFunctionContext ctx, 243 CeedMemType mem_type, bool *has_borrowed_data_of_type); 244 CEED_EXTERN int CeedQFunctionContextGetState(CeedQFunctionContext ctx, 245 uint64_t *state); 246 CEED_EXTERN int CeedQFunctionContextGetBackendData(CeedQFunctionContext ctx, 247 void *data); 248 CEED_EXTERN int CeedQFunctionContextSetBackendData(CeedQFunctionContext ctx, 249 void *data); 250 CEED_EXTERN int CeedQFunctionContextSetGeneric(CeedQFunctionContext ctx, 251 CeedContextFieldLabel field_label, 252 CeedContextFieldType field_type, void *value); 253 CEED_EXTERN int CeedQFunctionContextReference(CeedQFunctionContext ctx); 254 255 CEED_EXTERN int CeedQFunctionAssemblyDataCreate(Ceed ceed, CeedQFunctionAssemblyData *data); 256 CEED_EXTERN int CeedQFunctionAssemblyDataReference(CeedQFunctionAssemblyData data); 257 CEED_EXTERN int CeedQFunctionAssemblyDataSetReuse(CeedQFunctionAssemblyData data, bool reuse_assembly_data); 258 CEED_EXTERN int CeedQFunctionAssemblyDataSetUpdateNeeded(CeedQFunctionAssemblyData data, bool needs_data_update); 259 CEED_EXTERN int CeedQFunctionAssemblyDataIsUpdateNeeded(CeedQFunctionAssemblyData data, bool *is_update_needed); 260 CEED_EXTERN int CeedQFunctionAssemblyDataReferenceCopy(CeedQFunctionAssemblyData data, CeedQFunctionAssemblyData *data_copy); 261 CEED_EXTERN int CeedQFunctionAssemblyDataIsSetup(CeedQFunctionAssemblyData data, bool *is_setup); 262 CEED_EXTERN int CeedQFunctionAssemblyDataSetObjects(CeedQFunctionAssemblyData data, CeedVector vec, CeedElemRestriction rstr); 263 CEED_EXTERN int CeedQFunctionAssemblyDataGetObjects(CeedQFunctionAssemblyData data, CeedVector *vec, CeedElemRestriction *rstr); 264 CEED_EXTERN int CeedQFunctionAssemblyDataDestroy(CeedQFunctionAssemblyData *data); 265 266 CEED_EXTERN int CeedOperatorGetNumArgs(CeedOperator op, CeedInt *num_args); 267 CEED_EXTERN int CeedOperatorIsSetupDone(CeedOperator op, bool *is_setup_done); 268 CEED_EXTERN int CeedOperatorGetQFunction(CeedOperator op, CeedQFunction *qf); 269 CEED_EXTERN int CeedOperatorIsComposite(CeedOperator op, bool *is_composite); 270 CEED_EXTERN int CeedOperatorGetNumSub(CeedOperator op, CeedInt *num_suboperators); 271 CEED_EXTERN int CeedOperatorGetSubList(CeedOperator op, 272 CeedOperator **sub_operators); 273 CEED_EXTERN int CeedOperatorGetData(CeedOperator op, void *data); 274 CEED_EXTERN int CeedOperatorSetData(CeedOperator op, void *data); 275 CEED_EXTERN int CeedOperatorReference(CeedOperator op); 276 CEED_EXTERN int CeedOperatorSetSetupDone(CeedOperator op); 277 278 CEED_INTERN int CeedMatrixMultiply(Ceed ceed, const CeedScalar *mat_A, 279 const CeedScalar *mat_B, CeedScalar *mat_C, 280 CeedInt m, CeedInt n, CeedInt kk); 281 282 #endif 283