tvm
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros
c_runtime_api.h
Go to the documentation of this file.
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_runtime_api.h
22  * \brief TVM runtime library.
23  *
24  * The philosophy of TVM project is to customize the compilation
25  * stage to generate code that can used by other projects transparently.
26  * So this is a minimum runtime code gluing, and some limited
27  * memory management code to enable quick testing.
28  *
29  * The runtime API is independent from TVM compilation stack and can
30  * be linked via libtvm_runtime.
31  *
32  * The common flow is:
33  * - Use TVMFuncListGlobalNames to get global function name
34  * - Use TVMFuncCall to call these functions.
35  *
36  * Possible return values of the API functions:
37  * * 0: success
38  * * -1: the error can be retrieved through TVMGetLastError.
39  * * -2: a frontend error occurred and recorded in the frontend.
40  */
41 #ifndef TVM_RUNTIME_C_RUNTIME_API_H_
42 #define TVM_RUNTIME_C_RUNTIME_API_H_
43 
44 // Macros to do weak linking
45 #ifdef _MSC_VER
46 #define TVM_WEAK __declspec(selectany)
47 #else
48 #define TVM_WEAK __attribute__((weak))
49 #endif
50 
51 #ifdef __EMSCRIPTEN__
52 #include <emscripten/emscripten.h>
53 #define TVM_DLL EMSCRIPTEN_KEEPALIVE
54 #endif
55 
56 // helper macro to suppress unused warning
57 #if defined(__GNUC__)
58 #define TVM_ATTRIBUTE_UNUSED __attribute__((unused))
59 #else
60 #define TVM_ATTRIBUTE_UNUSED
61 #endif
62 
63 #ifndef TVM_DLL
64 #ifdef _WIN32
65 #ifdef TVM_EXPORTS
66 #define TVM_DLL __declspec(dllexport)
67 #else
68 #define TVM_DLL __declspec(dllimport)
69 #endif
70 #else
71 #define TVM_DLL __attribute__((visibility("default")))
72 #endif
73 #endif
74 
75 // TVM version
76 #define TVM_VERSION "0.20.dev0"
77 
78 // TVM Runtime is DLPack compatible.
79 #include <dlpack/dlpack.h>
80 
81 #ifdef __cplusplus
82 extern "C" {
83 #endif
84 #include <stdbool.h>
85 #include <stddef.h>
86 #include <stdint.h>
87 
89 typedef int64_t tvm_index_t;
90 
114 #ifdef __cplusplus
115 typedef enum : int32_t {
116 #else
117 typedef enum {
118 #endif
119  // To help avoid accidental conflicts between `DLDeviceType`
120  // and this enumeration, start numbering the new enumerators
121  // a little higher than (currently) seems necessary.
122  TVMDeviceExtType_End = 36, // sentinel value
124 
125 #ifdef __cplusplus
126 // Some other parts of TVM hardcode the integer identifier for
127 // some DLPack / TVM devices, rather then using the symbolic
128 // enumerator. E.g., `2` rather than `kDLCUDA`.
129 // These asserts should alert us when that mapping breaks.
130 #define TVM_HARCODED_INTEGER_CHANGED_MSG \
131  "Change in compile-time integer. Make sure hardcoded uses of this integer throughout TVM are " \
132  "updated."
133 static_assert(kDLCPU == 1, TVM_HARCODED_INTEGER_CHANGED_MSG);
134 static_assert(kDLCUDA == 2, TVM_HARCODED_INTEGER_CHANGED_MSG);
135 static_assert(kDLCUDAHost == 3, TVM_HARCODED_INTEGER_CHANGED_MSG);
136 static_assert(kDLOpenCL == 4, TVM_HARCODED_INTEGER_CHANGED_MSG);
137 static_assert(kDLVulkan == 7, TVM_HARCODED_INTEGER_CHANGED_MSG);
138 static_assert(kDLMetal == 8, TVM_HARCODED_INTEGER_CHANGED_MSG);
139 static_assert(kDLVPI == 9, TVM_HARCODED_INTEGER_CHANGED_MSG);
140 static_assert(kDLROCM == 10, TVM_HARCODED_INTEGER_CHANGED_MSG);
141 static_assert(kDLROCMHost == 11, TVM_HARCODED_INTEGER_CHANGED_MSG);
142 static_assert(kDLExtDev == 12, TVM_HARCODED_INTEGER_CHANGED_MSG);
143 static_assert(kDLCUDAManaged == 13, TVM_HARCODED_INTEGER_CHANGED_MSG);
144 static_assert(kDLOneAPI == 14, TVM_HARCODED_INTEGER_CHANGED_MSG);
145 static_assert(kDLWebGPU == 15, TVM_HARCODED_INTEGER_CHANGED_MSG);
146 static_assert(kDLHexagon == 16, TVM_HARCODED_INTEGER_CHANGED_MSG);
147 
148 #undef TVM_HARCODED_INTEGER_CHANGED_MSG
149 #endif
150 
167 typedef enum {
168  kTVMArgInt = kDLInt,
169  kTVMArgFloat = kDLFloat,
173  kDLDevice = 6U,
178  kTVMStr = 11U,
179  kTVMBytes = 12U,
182  kTVMArgBool = 15U,
183  // Extension codes for other frameworks to integrate TVM PackedFunc.
184  // To make sure each framework's id do not conflict, use first and
185  // last sections to mark ranges.
186  // Open an issue at the repo if you need a section of code.
190  // The following section of code is used for non-reserved types.
192  kTVMExtEnd = 128U,
194 
196 typedef DLTensor* TVMArrayHandle;
197 
202 typedef union {
203  int64_t v_int64;
204  double v_float64;
205  void* v_handle;
206  const char* v_str;
207  DLDataType v_type;
208  DLDevice v_device;
209 } TVMValue;
210 
215 typedef struct {
216  const char* data;
217  size_t size;
218 } TVMByteArray;
219 
221 typedef void* TVMModuleHandle;
223 typedef void* TVMFunctionHandle;
225 typedef void* TVMRetValueHandle;
230 typedef void* TVMStreamHandle;
232 typedef void* TVMObjectHandle;
233 
239 TVM_DLL void TVMAPISetLastError(const char* msg);
240 
246 TVM_DLL void TVMAPISetLastPythonError(void* py_object);
247 
258 TVM_DLL void* TVMGetLastPythonError();
259 
269 TVM_DLL const char* TVMGetLastError(void);
270 
280 TVM_DLL const char* TVMGetLastBacktrace();
281 
294 TVM_DLL void TVMDropLastPythonError();
295 
304 TVM_DLL void TVMThrowLastError();
305 
316 TVM_DLL int TVMModLoadFromFile(const char* file_name, const char* format, TVMModuleHandle* out);
317 
327 
336 TVM_DLL int TVMModGetFunction(TVMModuleHandle mod, const char* func_name, int query_imports,
337  TVMFunctionHandle* out);
338 
351 
357 TVM_DLL int TVMFuncFree(TVMFunctionHandle func);
358 
379 TVM_DLL int TVMFuncCall(TVMFunctionHandle func, TVMValue* arg_values, int* type_codes, int num_args,
380  TVMValue* ret_val, int* ret_type_code);
381 
393 TVM_DLL int TVMCFuncSetReturn(TVMRetValueHandle ret, TVMValue* value, int* type_code, int num_ret);
394 
405 TVM_DLL int TVMCbArgToReturn(TVMValue* value, int* code);
406 
418 typedef int (*TVMPackedCFunc)(TVMValue* args, int* type_codes, int num_args, TVMRetValueHandle ret,
419  void* resource_handle);
420 
425 typedef void (*TVMPackedCFuncFinalizer)(void* resource_handle);
426 
436 typedef int (*TVMExtensionFuncDeclarer)(TVMFunctionHandle register_func_handle);
437 
449 TVM_DLL int TVMFuncCreateFromCFunc(TVMPackedCFunc func, void* resource_handle,
451 
461 TVM_DLL int TVMFuncRegisterGlobal(const char* name, TVMFunctionHandle f, int override);
462 
472 TVM_DLL int TVMFuncGetGlobal(const char* name, TVMFunctionHandle* out);
473 
480 TVM_DLL int TVMFuncListGlobalNames(int* out_size, const char*** out_array);
481 
486 TVM_DLL int TVMFuncRemoveGlobal(const char* name);
487 
488 // Array related apis for quick proptyping
503 TVM_DLL int TVMArrayAlloc(const tvm_index_t* shape, int ndim, int dtype_code, int dtype_bits,
504  int dtype_lanes, int device_type, int device_id, TVMArrayHandle* out);
505 
511 TVM_DLL int TVMArrayFree(TVMArrayHandle handle);
512 
520 TVM_DLL int TVMArrayCopyFromBytes(TVMArrayHandle handle, void* data, size_t nbytes);
521 
529 TVM_DLL int TVMArrayCopyToBytes(TVMArrayHandle handle, void* data, size_t nbytes);
530 
539 
547 TVM_DLL int TVMArrayFromDLPack(DLManagedTensor* from, TVMArrayHandle* out);
548 
556 TVM_DLL int TVMArrayToDLPack(TVMArrayHandle from, DLManagedTensor** out);
557 
562 TVM_DLL void TVMDLManagedTensorCallDeleter(DLManagedTensor* dltensor);
563 
573 
582 TVM_DLL int TVMStreamFree(int device_type, int device_id, TVMStreamHandle stream);
583 
595 TVM_DLL int TVMSetStream(int device_type, int device_id, TVMStreamHandle handle);
596 
605 TVM_DLL int TVMSynchronize(int device_type, int device_id, TVMStreamHandle stream);
606 
617  TVMStreamHandle dst);
618 
626 TVM_DLL int TVMObjectGetTypeIndex(TVMObjectHandle obj, unsigned* out_tindex);
627 
634 TVM_DLL int TVMObjectTypeKey2Index(const char* type_key, unsigned* out_tindex);
635 
642 TVM_DLL int TVMObjectTypeIndex2Key(unsigned tindex, char** out_type_key);
643 
652 
662 
668 TVM_DLL int TVMByteArrayFree(TVMByteArray* arr);
669 
680 TVM_DLL int TVMDeviceAllocDataSpace(DLDevice dev, size_t nbytes, size_t alignment,
681  DLDataType type_hint, void** out_data);
682 
696 TVM_DLL int TVMDeviceAllocDataSpaceWithScope(DLDevice dev, int ndim, const int64_t* shape,
697  DLDataType dtype, const char* mem_scope,
698  void** out_data);
699 
706 TVM_DLL int TVMDeviceFreeDataSpace(DLDevice dev, void* ptr);
707 
717 TVM_DLL int TVMDeviceCopyDataFromTo(DLTensor* from, DLTensor* to, TVMStreamHandle stream);
718 
726 TVM_DLL int TVMObjectDerivedFrom(uint32_t child_type_index, uint32_t parent_type_index,
727  int* is_derived);
728 
729 #ifdef __cplusplus
730 } // TVM_EXTERN_C
731 #endif
732 #endif // TVM_RUNTIME_C_RUNTIME_API_H_
int TVMArrayAlloc(const tvm_index_t *shape, int ndim, int dtype_code, int dtype_bits, int dtype_lanes, int device_type, int device_id, TVMArrayHandle *out)
Allocate a nd-array's memory, including space of shape, of given spec.
int TVMDeviceFreeDataSpace(DLDevice dev, void *ptr)
Free a data space on device.
int TVMDeviceAllocDataSpace(DLDevice dev, size_t nbytes, size_t alignment, DLDataType type_hint, void **out_data)
Allocate a data space on device.
int(* TVMPackedCFunc)(TVMValue *args, int *type_codes, int num_args, TVMRetValueHandle ret, void *resource_handle)
C type of packed function.
Definition: c_runtime_api.h:418
int TVMArrayCopyFromTo(TVMArrayHandle from, TVMArrayHandle to, TVMStreamHandle stream)
Copy the array, both from and to must be valid during the copy.
TVMArgTypeCode
The type code in used and only used in TVM FFI for argument passing.
Definition: c_runtime_api.h:167
@ kTVMExtReserveEnd
Definition: c_runtime_api.h:191
@ kTVMExtBegin
Definition: c_runtime_api.h:187
@ kTVMPackedFuncHandle
Definition: c_runtime_api.h:177
@ kTVMNNVMLast
Definition: c_runtime_api.h:189
@ kTVMNDArrayHandle
Definition: c_runtime_api.h:180
@ kTVMModuleHandle
Definition: c_runtime_api.h:176
@ kTVMExtEnd
Definition: c_runtime_api.h:192
@ kTVMBytes
Definition: c_runtime_api.h:179
@ kTVMNNVMFirst
Definition: c_runtime_api.h:188
@ kTVMDataType
Definition: c_runtime_api.h:172
@ kTVMArgBool
Definition: c_runtime_api.h:182
@ kTVMArgInt
Definition: c_runtime_api.h:168
@ kTVMDLTensorHandle
Definition: c_runtime_api.h:174
@ kDLDevice
Definition: c_runtime_api.h:173
@ kTVMOpaqueHandle
Definition: c_runtime_api.h:170
@ kTVMObjectHandle
Definition: c_runtime_api.h:175
@ kTVMObjectRValueRefArg
Definition: c_runtime_api.h:181
@ kTVMNullptr
Definition: c_runtime_api.h:171
@ kTVMArgFloat
Definition: c_runtime_api.h:169
@ kTVMStr
Definition: c_runtime_api.h:178
int TVMObjectDerivedFrom(uint32_t child_type_index, uint32_t parent_type_index, int *is_derived)
Check that an object is derived from another.
const char * TVMGetLastBacktrace()
Return the backtrace of the most recent error.
int TVMSynchronize(int device_type, int device_id, TVMStreamHandle stream)
Wait until all computations on stream completes.
int TVMFuncListGlobalNames(int *out_size, const char ***out_array)
List all the globally registered function name.
int(* TVMExtensionFuncDeclarer)(TVMFunctionHandle register_func_handle)
Signature for extension function declarer.
Definition: c_runtime_api.h:436
void TVMAPISetLastError(const char *msg)
Used for implementing C API function. Set last error message before return.
int TVMModLoadFromFile(const char *file_name, const char *format, TVMModuleHandle *out)
Load module from file.
int TVMArrayCopyFromBytes(TVMArrayHandle handle, void *data, size_t nbytes)
Copy array data from CPU byte array.
int TVMDeviceAllocDataSpaceWithScope(DLDevice dev, int ndim, const int64_t *shape, DLDataType dtype, const char *mem_scope, void **out_data)
Allocate a data space on device with special memory scope.
TVMDeviceExtType
Extension device types in TVM.
Definition: c_runtime_api.h:117
@ TVMDeviceExtType_End
Definition: c_runtime_api.h:122
int TVMArrayFree(TVMArrayHandle handle)
Free the TVM Array.
int TVMModGetFunction(TVMModuleHandle mod, const char *func_name, int query_imports, TVMFunctionHandle *out)
Get function from the module.
void TVMAPISetLastPythonError(void *py_object)
Used for implementing C API function. Set last exception before return.
void TVMDLManagedTensorCallDeleter(DLManagedTensor *dltensor)
Delete (free) a DLManagedTensor's data.
int TVMObjectFree(TVMObjectHandle obj)
Free the object.
void * TVMRetValueHandle
Handle to hold return value.
Definition: c_runtime_api.h:225
int TVMCbArgToReturn(TVMValue *value, int *code)
Inplace translate callback argument value to return value. This is only needed for non-POD arguments.
int TVMStreamCreate(int device_type, int device_id, TVMStreamHandle *out)
Create a new runtime stream.
DLTensor * TVMArrayHandle
the array handle
Definition: c_runtime_api.h:196
const char * TVMGetLastError(void)
return str message of the last error all function in this file will return 0 when success and nonzero...
int TVMObjectTypeKey2Index(const char *type_key, unsigned *out_tindex)
Convert type key to type index.
int TVMFuncCall(TVMFunctionHandle func, TVMValue *arg_values, int *type_codes, int num_args, TVMValue *ret_val, int *ret_type_code)
Call a Packed TVM Function.
int TVMFuncRegisterGlobal(const char *name, TVMFunctionHandle f, int override)
Register the function to runtime's global table.
int TVMStreamFree(int device_type, int device_id, TVMStreamHandle stream)
Free a created stream handle.
int TVMDeviceCopyDataFromTo(DLTensor *from, DLTensor *to, TVMStreamHandle stream)
Copy data from one place to another.
int TVMStreamStreamSynchronize(int device_type, int device_id, TVMStreamHandle src, TVMStreamHandle dst)
Synchronize two streams of execution.
int TVMByteArrayFree(TVMByteArray *arr)
Free a TVMByteArray returned from TVMFuncCall, and associated memory.
int TVMModImport(TVMModuleHandle mod, TVMModuleHandle dep)
Add dep to mod's dependency. This allows functions in this module to use modules.
void * TVMStreamHandle
The stream that is specific to device can be NULL, which indicates the default one.
Definition: c_runtime_api.h:230
void * TVMGetLastPythonError()
Return the previous python error, if any.
void TVMDropLastPythonError()
Remove the propagated python error, if any.
int TVMFuncRemoveGlobal(const char *name)
Remove a global function.
int TVMObjectGetTypeIndex(TVMObjectHandle obj, unsigned *out_tindex)
Get the type_index from an object.
void(* TVMPackedCFuncFinalizer)(void *resource_handle)
C callback to free the resource handle in C packed function.
Definition: c_runtime_api.h:425
int TVMModFree(TVMModuleHandle mod)
Free the Module.
int TVMSetStream(int device_type, int device_id, TVMStreamHandle handle)
Set the runtime stream of current thread to be stream. The subsequent calls to the same device_type w...
void * TVMModuleHandle
Handle to TVM runtime modules.
Definition: c_runtime_api.h:221
void TVMThrowLastError()
Re-throw the most recent error.
int64_t tvm_index_t
type of array index.
Definition: c_runtime_api.h:89
void * TVMFunctionHandle
Handle to packed function handle.
Definition: c_runtime_api.h:223
int TVMCFuncSetReturn(TVMRetValueHandle ret, TVMValue *value, int *type_code, int num_ret)
Set the return value of TVMPackedCFunc.
int TVMFuncGetGlobal(const char *name, TVMFunctionHandle *out)
Get a global function.
int TVMArrayFromDLPack(DLManagedTensor *from, TVMArrayHandle *out)
Produce an array from the DLManagedTensor that shares data memory with the DLManagedTensor.
int TVMFuncCreateFromCFunc(TVMPackedCFunc func, void *resource_handle, TVMPackedCFuncFinalizer fin, TVMFunctionHandle *out)
Wrap a TVMPackedCFunc to become a FunctionHandle.
int TVMArrayCopyToBytes(TVMArrayHandle handle, void *data, size_t nbytes)
Copy array data to CPU byte array.
int TVMArrayToDLPack(TVMArrayHandle from, DLManagedTensor **out)
Produce a DLMangedTensor from the array that shares data memory with the array.
int TVMObjectTypeIndex2Key(unsigned tindex, char **out_type_key)
Convert type index to type key.
int TVMObjectRetain(TVMObjectHandle obj)
Increase the reference count of an object.
int TVMFuncFree(TVMFunctionHandle func)
Free the function when it is no longer needed.
void * TVMObjectHandle
Handle to Object.
Definition: c_runtime_api.h:232
constexpr const char * device_id
The allocation device for global malloc in host.
Definition: stmt.h:1420
constexpr const char * device_type
The device type.
Definition: stmt.h:1422
const Op & ret()
Return value.
tvm::PrimExpr mod(const tvm::PrimExpr &a, const tvm::PrimExpr &b)
Definition: broadcast.h:290
Tensor shape(const Tensor &src, DataType dtype, const std::string name="T_shape", const std::string tag=kInjective)
Get the shape of input tensor.
Definition: transform.h:1913
Byte array type used to pass in byte array When kTVMBytes is used as data type.
Definition: c_runtime_api.h:215
size_t size
Definition: c_runtime_api.h:217
const char * data
Definition: c_runtime_api.h:216
Union type of values being passed through API and function calls.
Definition: c_runtime_api.h:202
DLDevice v_device
Definition: c_runtime_api.h:208
void * v_handle
Definition: c_runtime_api.h:205
DLDataType v_type
Definition: c_runtime_api.h:207
int64_t v_int64
Definition: c_runtime_api.h:203
const char * v_str
Definition: c_runtime_api.h:206
double v_float64
Definition: c_runtime_api.h:204