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 tvm/runtime/c_backend_api.h |
22 | * \brief TVM runtime backend API. |
23 | * |
24 | * The functions defined in this header are intended to be |
25 | * used by compiled tvm operators, usually user do not need to use these |
26 | * function directly. |
27 | */ |
28 | #ifndef TVM_RUNTIME_C_BACKEND_API_H_ |
29 | #define TVM_RUNTIME_C_BACKEND_API_H_ |
30 | |
31 | #include <tvm/runtime/c_runtime_api.h> |
32 | |
33 | #ifdef __cplusplus |
34 | extern "C" { |
35 | #endif |
36 | |
37 | /*! |
38 | * \brief Signature for backend functions exported as DLL. |
39 | * |
40 | * \param args The arguments |
41 | * \param type_codes The type codes of the arguments |
42 | * \param num_args Number of arguments. |
43 | * \param out_ret_value The output value of the return value. |
44 | * \param out_ret_tcode The output type code of the return value. |
45 | * \param resource_handle Pointer to associated resource. |
46 | * |
47 | * \return 0 if success, -1 if failure happens, set error via TVMAPISetLastError. |
48 | */ |
49 | typedef int (*TVMBackendPackedCFunc)(TVMValue* args, int* type_codes, int num_args, |
50 | TVMValue* out_ret_value, int* out_ret_tcode, |
51 | void* resource_handle); |
52 | |
53 | /*! |
54 | * \brief Backend function for modules to get function |
55 | * from its environment mod_node (its imports and global function). |
56 | * The user do should not call TVMFuncFree on func. |
57 | * |
58 | * \param mod_node The module handle. |
59 | * \param func_name The name of the function. |
60 | * \param out The result function. |
61 | * \return 0 when no error is thrown, -1 when failure happens |
62 | */ |
63 | TVM_DLL int TVMBackendGetFuncFromEnv(void* mod_node, const char* func_name, TVMFunctionHandle* out); |
64 | |
65 | /*! |
66 | * \brief Backend function to register system-wide library symbol. |
67 | * |
68 | * \param name The name of the symbol |
69 | * \param ptr The symbol address. |
70 | * \return 0 when no error is thrown, -1 when failure happens |
71 | */ |
72 | TVM_DLL int TVMBackendRegisterSystemLibSymbol(const char* name, void* ptr); |
73 | |
74 | /*! |
75 | * \brief Backend function to allocate temporal workspace. |
76 | * |
77 | * \note The result allocated space is ensured to be aligned to kTempAllocaAlignment. |
78 | * |
79 | * \param nbytes The size of the space requested. |
80 | * \param device_type The device type which the space will be allocated. |
81 | * \param device_id The device id which the space will be allocated. |
82 | * \param dtype_code_hint The type code of the array elements. Only used in |
83 | * certain backends such as OpenGL. |
84 | * \param dtype_bits_hint The type bits of the array elements. Only used in |
85 | * certain backends such as OpenGL. |
86 | * \return nullptr when error is thrown, a valid ptr if success |
87 | */ |
88 | TVM_DLL void* TVMBackendAllocWorkspace(int device_type, int device_id, uint64_t nbytes, |
89 | int dtype_code_hint, int dtype_bits_hint); |
90 | |
91 | /*! |
92 | * \brief Backend function to free temporal workspace. |
93 | * |
94 | * \param ptr The result allocated space pointer. |
95 | * \param device_type The device type which the space will be allocated. |
96 | * \param device_id The device id which the space will be allocated. |
97 | * \return 0 when no error is thrown, -1 when failure happens |
98 | * |
99 | * \sa TVMBackendAllocWorkspace |
100 | */ |
101 | TVM_DLL int TVMBackendFreeWorkspace(int device_type, int device_id, void* ptr); |
102 | |
103 | /*! |
104 | * \brief Backend function to register execution environment(e.g. python) |
105 | * specific C APIs. |
106 | * |
107 | * \note We only register the C API function when absolutely necessary (e.g. when signal handler |
108 | * cannot trap back into python). In most cases we should use the PackedFunc FFI. |
109 | * |
110 | * \param name The name of the symbol |
111 | * \param ptr The symbol address. |
112 | * \return 0 when no error is thrown, -1 when failure happens |
113 | */ |
114 | TVM_DLL int TVMBackendRegisterEnvCAPI(const char* name, void* ptr); |
115 | |
116 | /*! |
117 | * \brief Environment for TVM parallel task. |
118 | */ |
119 | typedef struct { |
120 | /*! |
121 | * \brief Auxiliary used for synchronization |
122 | */ |
123 | void* sync_handle; |
124 | /*! \brief total amount of task */ |
125 | int32_t num_task; |
126 | } TVMParallelGroupEnv; |
127 | |
128 | /*! |
129 | * \brief The callback function to execute a parallel lambda |
130 | * \param task_id the task id of the function. |
131 | * \param penv The parallel environment backs the execution. |
132 | * \param cdata The supporting closure data. |
133 | */ |
134 | typedef int (*FTVMParallelLambda)(int task_id, TVMParallelGroupEnv* penv, void* cdata); |
135 | |
136 | /*! |
137 | * \brief Backend function for running parallel jobs. |
138 | * |
139 | * \param flambda The parallel function to be launched. |
140 | * \param cdata The closure data. |
141 | * \param num_task Number of tasks to launch, can be 0, means launch |
142 | * with all available threads. |
143 | * |
144 | * \return 0 when no error is thrown, -1 when failure happens |
145 | */ |
146 | TVM_DLL int TVMBackendParallelLaunch(FTVMParallelLambda flambda, void* cdata, int num_task); |
147 | |
148 | /*! |
149 | * \brief BSP barrrier between parallel threads |
150 | * \param task_id the task id of the function. |
151 | * \param penv The parallel environment backs the execution. |
152 | * \return 0 when no error is thrown, -1 when failure happens |
153 | */ |
154 | TVM_DLL int TVMBackendParallelBarrier(int task_id, TVMParallelGroupEnv* penv); |
155 | |
156 | /*! |
157 | * \brief Simple static initialization function. |
158 | * Run f once and set handle to be not null. |
159 | * This function is mainly used for test purpose. |
160 | * |
161 | * \param handle A global address to indicate f |
162 | * \param f The function to be run |
163 | * \param cdata The closure data to pass to the function. |
164 | * \param nbytes Number of bytes in the closure data. |
165 | * \return 0 when no error is thrown, -1 when failure happens |
166 | */ |
167 | TVM_DLL int TVMBackendRunOnce(void** handle, int (*f)(void*), void* cdata, int nbytes); |
168 | |
169 | #ifdef __cplusplus |
170 | } // TVM_EXTERN_C |
171 | #endif |
172 | #endif // TVM_RUNTIME_C_BACKEND_API_H_ |
173 | |