c_runtime_api.h

Go to the documentation of this file.

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */

/*
 * \file tvm/runtime/c_runtime_api.h
 * \brief TVM runtime library.
 *
 *  The philosophy of TVM project is to customize the compilation
 *  stage to generate code that can used by other projects transparently.
 *  So this is a minimum runtime code gluing, and some limited
 *  memory management code to enable quick testing.
 *
 *  The runtime API is independent from TVM compilation stack and can
 *  be linked via libtvm_runtime.
 *
 *  The common flow is:
 *   - Use TVMFuncListGlobalNames to get global function name
 *   - Use TVMFuncCall to call these functions.
 */
#ifndef TVM_RUNTIME_C_RUNTIME_API_H_
#define TVM_RUNTIME_C_RUNTIME_API_H_

// Macros to do weak linking
#ifdef _MSC_VER
#define TVM_WEAK __declspec(selectany)
#else
#define TVM_WEAK __attribute__((weak))
#endif

#ifdef __EMSCRIPTEN__
#include <emscripten/emscripten.h>
#define TVM_DLL EMSCRIPTEN_KEEPALIVE
#endif

#ifndef TVM_DLL
#ifdef _WIN32
#ifdef TVM_EXPORTS
#define TVM_DLL __declspec(dllexport)
#else
#define TVM_DLL __declspec(dllimport)
#endif
#else
#define TVM_DLL __attribute__((visibility("default")))
#endif
#endif

// TVM version
#define TVM_VERSION "0.6.dev"


// TVM Runtime is DLPack compatible.
#include <dlpack/dlpack.h>

#ifdef __cplusplus
extern "C" {
#endif
#include <stdint.h>
#include <stddef.h>

typedef int64_t tvm_index_t;

typedef enum {
  kDLAOCL = 5,
  kDLSDAccel = 6,
  kOpenGL = 11,
  kDLMicroDev = 13,
  // AddExtraTVMType which is not in DLPack here
} TVMDeviceExtType;

typedef enum {
  // The type code of other types are compatible with DLPack.
  // The next few fields are extension types
  // that is used by TVM API calls.
  kHandle = 3U,
  kNull = 4U,
  kTVMType = 5U,
  kTVMContext = 6U,
  kArrayHandle = 7U,
  kNodeHandle = 8U,
  kModuleHandle = 9U,
  kFuncHandle = 10U,
  kStr = 11U,
  kBytes = 12U,
  kNDArrayContainer = 13U,
  kObjectCell = 14U,
  // Extension codes for other frameworks to integrate TVM PackedFunc.
  // To make sure each framework's id do not conflict, use first and
  // last sections to mark ranges.
  // Open an issue at the repo if you need a section of code.
  kExtBegin = 15U,
  kNNVMFirst = 16U,
  kNNVMLast = 20U,
  // The following section of code is used for non-reserved types.
  kExtReserveEnd = 64U,
  kExtEnd = 128U,
  // The rest of the space is used for custom, user-supplied datatypes
  kCustomBegin = 129U,
} TVMTypeCode;

typedef DLDataType TVMType;

typedef DLContext TVMContext;

typedef DLTensor TVMArray;

typedef TVMArray* TVMArrayHandle;

typedef union {
  int64_t v_int64;
  double v_float64;
  void* v_handle;
  const char* v_str;
  TVMType v_type;
  TVMContext v_ctx;
} TVMValue;

typedef struct {
  const char* data;
  size_t size;
} TVMByteArray;

typedef void* TVMModuleHandle;
typedef void* TVMFunctionHandle;
typedef void* TVMRetValueHandle;
typedef void* TVMStreamHandle;
typedef void* TVMObjectHandle;

TVM_DLL void TVMAPISetLastError(const char* msg);

TVM_DLL const char *TVMGetLastError(void);
TVM_DLL int TVMModLoadFromFile(const char* file_name,
                               const char* format,
                               TVMModuleHandle* out);

TVM_DLL int TVMModImport(TVMModuleHandle mod,
                         TVMModuleHandle dep);

TVM_DLL int TVMModGetFunction(TVMModuleHandle mod,
                              const char* func_name,
                              int query_imports,
                              TVMFunctionHandle *out);

TVM_DLL int TVMExtTypeFree(void* handle, int type_code);

TVM_DLL int TVMModFree(TVMModuleHandle mod);

TVM_DLL int TVMFuncFree(TVMFunctionHandle func);

TVM_DLL int TVMFuncCall(TVMFunctionHandle func,
                        TVMValue* arg_values,
                        int* type_codes,
                        int num_args,
                        TVMValue* ret_val,
                        int* ret_type_code);

TVM_DLL int TVMCFuncSetReturn(TVMRetValueHandle ret,
                              TVMValue* value,
                              int* type_code,
                              int num_ret);

TVM_DLL int TVMCbArgToReturn(TVMValue* value, int code);

typedef int (*TVMPackedCFunc)(
    TVMValue* args,
    int* type_codes,
    int num_args,
    TVMRetValueHandle ret,
    void* resource_handle);

typedef void (*TVMPackedCFuncFinalizer)(void* resource_handle);

typedef int (*TVMExtensionFuncDeclarer)(TVMFunctionHandle register_func_handle);

TVM_DLL int TVMFuncCreateFromCFunc(TVMPackedCFunc func,
                                   void* resource_handle,
                                   TVMPackedCFuncFinalizer fin,
                                   TVMFunctionHandle *out);

TVM_DLL int TVMFuncRegisterGlobal(
    const char* name, TVMFunctionHandle f, int override);

TVM_DLL int TVMFuncGetGlobal(const char* name, TVMFunctionHandle* out);

TVM_DLL int TVMFuncListGlobalNames(int* out_size,
                                   const char*** out_array);

// Array related apis for quick proptyping
TVM_DLL 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);

TVM_DLL int TVMArrayFree(TVMArrayHandle handle);

TVM_DLL int TVMArrayCopyFromBytes(TVMArrayHandle handle,
                                  void* data,
                                  size_t nbytes);

TVM_DLL int TVMArrayCopyToBytes(TVMArrayHandle handle,
                                void* data,
                                size_t nbytes);

TVM_DLL int TVMArrayCopyFromTo(TVMArrayHandle from,
                               TVMArrayHandle to,
                               TVMStreamHandle stream);

TVM_DLL int TVMArrayFromDLPack(DLManagedTensor* from,
                               TVMArrayHandle* out);

TVM_DLL int TVMArrayToDLPack(TVMArrayHandle from,
                             DLManagedTensor** out);

TVM_DLL void TVMDLManagedTensorCallDeleter(DLManagedTensor* dltensor);

TVM_DLL int TVMStreamCreate(int device_type, int device_id, TVMStreamHandle* out);

TVM_DLL int TVMStreamFree(int device_type, int device_id, TVMStreamHandle stream);

TVM_DLL int TVMSetStream(int device_type, int device_id, TVMStreamHandle handle);

TVM_DLL int TVMSynchronize(int device_type, int device_id, TVMStreamHandle stream);

TVM_DLL int TVMStreamStreamSynchronize(int device_type,
                                       int device_id,
                                       TVMStreamHandle src,
                                       TVMStreamHandle dst);

TVM_DLL int TVMGetObjectTag(TVMObjectHandle obj, int* tag);

#ifdef __cplusplus
}  // TVM_EXTERN_C
#endif
#endif  // TVM_RUNTIME_C_RUNTIME_API_H_