1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, 13 * software distributed under the License is distributed on an 14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 15 * KIND, either express or implied. See the License for the 16 * specific language governing permissions and limitations 17 * under the License. 18 */ 19 20 /* 21 * \file c_runtime_api.h 22 * \brief MXNet runtime library. 23 */ 24 // Acknowledgement: This file originates from incubator-tvm 25 #ifndef MXNET_RUNTIME_C_RUNTIME_API_H_ 26 #define MXNET_RUNTIME_C_RUNTIME_API_H_ 27 28 #include <dlpack/dlpack.h> 29 30 #ifdef __cplusplus 31 extern "C" { 32 #endif 33 #include <mxnet/c_api.h> 34 #include <stdint.h> 35 #include <stddef.h> 36 37 38 /*! 39 * \brief The type code in MXNetType 40 * \note MXNetType is used in two places. 41 */ 42 typedef enum { 43 // The type code of other types are compatible with DLPack. 44 // The next few fields are extension types 45 // that is used by MXNet API calls. 46 kHandle = 3U, 47 kNull = 4U, 48 kMXNetType = 5U, 49 kMXNetContext = 6U, 50 kArrayHandle = 7U, 51 kObjectHandle = 8U, 52 kModuleHandle = 9U, 53 kFuncHandle = 10U, 54 kStr = 11U, 55 kBytes = 12U, 56 kNDArrayContainer = 13U, 57 kNDArrayHandle = 14U, 58 // Extension codes for other frameworks to integrate MXNet PackedFunc. 59 // To make sure each framework's id do not conflict, use first and 60 // last sections to mark ranges. 61 // Open an issue at the repo if you need a section of code. 62 kExtBegin = 15U, 63 kNNVMFirst = 16U, 64 kNNVMLast = 20U, 65 // The following section of code is used for non-reserved types. 66 kExtReserveEnd = 64U, 67 kExtEnd = 128U, 68 // The rest of the space is used for custom, user-supplied datatypes 69 kCustomBegin = 129U, 70 } MXNetTypeCode; 71 72 /*! 73 * \brief Union type of values 74 * being passed through API and function calls. 75 */ 76 typedef union { 77 int64_t v_int64; 78 double v_float64; 79 void* v_handle; 80 const char* v_str; 81 DLDataType v_type; 82 } MXNetValue; 83 84 /*! 85 * \brief Byte array type used to pass in byte array 86 * When kBytes is used as data type. 87 */ 88 typedef struct { 89 const char* data; 90 size_t size; 91 } MXNetByteArray; 92 93 /*! \brief Handle to packed function handle. */ 94 typedef void* MXNetFunctionHandle; 95 /*! \brief Handle to Object. */ 96 typedef void* MXNetObjectHandle; 97 98 /*! 99 * \brief Free the function when it is no longer needed. 100 * \param func The function handle 101 * \return 0 when success, -1 when failure happens 102 */ 103 MXNET_DLL int MXNetFuncFree(MXNetFunctionHandle func); 104 105 /*! 106 * \brief Call a Packed MXNet Function. 107 * 108 * \param func node handle of the function. 109 * \param arg_values The arguments 110 * \param type_codes The type codes of the arguments 111 * \param num_args Number of arguments. 112 * 113 * \param ret_val The return value. 114 * \param ret_type_code the type code of return value. 115 * 116 * \return 0 when success, -1 when failure happens 117 * \note MXNet calls always exchanges with type bits=64, lanes=1 118 * 119 * \note API calls always exchanges with type bits=64, lanes=1 120 * If API call returns container handles (e.g. FunctionHandle) 121 * these handles should be managed by the front-end. 122 * The front-end need to call free function (e.g. MXNetFuncFree) 123 * to free these handles. 124 */ 125 MXNET_DLL int MXNetFuncCall(MXNetFunctionHandle func, 126 MXNetValue* arg_values, 127 int* type_codes, 128 int num_args, 129 MXNetValue* ret_val, 130 int* ret_type_code); 131 132 /*! 133 * \brief Get a global function. 134 * 135 * \param name The name of the function. 136 * \param out the result function pointer, NULL if it does not exist. 137 * 138 * \note The function handle of global function is managed by MXNet runtime, 139 * So MXNetFuncFree is should not be called when it get deleted. 140 */ 141 MXNET_DLL int MXNetFuncGetGlobal(const char* name, MXNetFunctionHandle* out); 142 143 /*! 144 * \brief List all the globally registered function name 145 * \param out_size The number of functions 146 * \param out_array The array of function names. 147 * \return 0 when success, -1 when failure happens 148 */ 149 MXNET_DLL int MXNetFuncListGlobalNames(int* out_size, 150 const char*** out_array); 151 152 /*! 153 * \brief Free the object. 154 * 155 * \param obj The object handle. 156 * \note Internally we decrease the reference counter of the object. 157 * The object will be freed when every reference to the object are removed. 158 * \return 0 when success, -1 when failure happens 159 */ 160 MXNET_DLL int MXNetObjectFree(MXNetObjectHandle obj); 161 162 #ifdef __cplusplus 163 } // extern "C" 164 #endif 165 #endif // MXNET_RUNTIME_C_RUNTIME_API_H_ 166