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
34extern "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 */
49typedef 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 */
63TVM_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 */
72TVM_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 */
88TVM_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 */
101TVM_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 */
114TVM_DLL int TVMBackendRegisterEnvCAPI(const char* name, void* ptr);
115
116/*!
117 * \brief Environment for TVM parallel task.
118 */
119typedef 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 */
134typedef 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 */
146TVM_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 */
154TVM_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 */
167TVM_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