tvm
Classes | Macros | Typedefs | Enumerations | Functions
c_runtime_api.h File Reference
#include <dlpack/dlpack.h>
#include <stdint.h>
#include <stddef.h>
Include dependency graph for c_runtime_api.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

union  TVMValue
 Union type of values being passed through API and function calls. More...
 
struct  TVMByteArray
 Byte array type used to pass in byte array When kBytes is used as data type. More...
 

Macros

#define TVM_WEAK   __attribute__((weak))
 
#define TVM_VERSION   "0.6.dev"
 

Typedefs

typedef int64_t tvm_index_t
 type of array index. More...
 
typedef DLDataType TVMType
 The data type used in TVM Runtime. More...
 
typedef DLContext TVMContext
 The Device information, abstract away common device types. More...
 
typedef DLTensor TVMArray
 The tensor array stucture to TVM API. More...
 
typedef TVMArrayTVMArrayHandle
 the array handle More...
 
typedef void * TVMModuleHandle
 Handle to TVM runtime modules. More...
 
typedef void * TVMFunctionHandle
 Handle to packed function handle. More...
 
typedef void * TVMRetValueHandle
 Handle to hold return value. More...
 
typedef void * TVMStreamHandle
 The stream that is specific to device can be NULL, which indicates the default one. More...
 
typedef int(* TVMPackedCFunc) (TVMValue *args, int *type_codes, int num_args, TVMRetValueHandle ret, void *resource_handle)
 C type of packed function. More...
 
typedef void(* TVMPackedCFuncFinalizer) (void *resource_handle)
 C callback to free the resource handle in C packed function. More...
 
typedef int(* TVMExtensionFuncDeclarer) (TVMFunctionHandle register_func_handle)
 Signature for extension function declarer. More...
 

Enumerations

enum  TVMDeviceExtType { kDLAOCL = 5, kDLSDAccel = 6, kOpenGL = 11 }
 Extension device types in TVM. More...
 
enum  TVMTypeCode {
  kHandle = 3U, kNull = 4U, kTVMType = 5U, kTVMContext = 6U,
  kArrayHandle = 7U, kNodeHandle = 8U, kModuleHandle = 9U, kFuncHandle = 10U,
  kStr = 11U, kBytes = 12U, kNDArrayContainer = 13U, kObject = 14U,
  kExtBegin = 15U, kNNVMFirst = 16U, kNNVMLast = 20U, kExtReserveEnd = 64U,
  kExtEnd = 128U, kCustomBegin = 128U
}
 The type code in TVMType. More...
 

Functions

void TVMAPISetLastError (const char *msg)
 Used for implementing C API function. Set last error message before return. More...
 
const char * TVMGetLastError (void)
 return str message of the last error all function in this file will return 0 when success and -1 when an error occured, TVMGetLastError can be called to retrieve the error More...
 
int TVMModLoadFromFile (const char *file_name, const char *format, TVMModuleHandle *out)
 Load module from file. More...
 
int TVMModImport (TVMModuleHandle mod, TVMModuleHandle dep)
 Add dep to mod's dependency. This allows functions in this module to use modules. More...
 
int TVMModGetFunction (TVMModuleHandle mod, const char *func_name, int query_imports, TVMFunctionHandle *out)
 Get function from the module. More...
 
int TVMExtTypeFree (void *handle, int type_code)
 Free front-end extension type resource. More...
 
int TVMModFree (TVMModuleHandle mod)
 Free the Module. More...
 
int TVMFuncFree (TVMFunctionHandle func)
 Free the function when it is no longer needed. More...
 
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. More...
 
int TVMCFuncSetReturn (TVMRetValueHandle ret, TVMValue *value, int *type_code, int num_ret)
 Set the return value of TVMPackedCFunc. More...
 
int TVMCbArgToReturn (TVMValue *value, int code)
 Inplace translate callback argument value to return value. This is only needed for non-POD arguments. More...
 
int TVMFuncCreateFromCFunc (TVMPackedCFunc func, void *resource_handle, TVMPackedCFuncFinalizer fin, TVMFunctionHandle *out)
 Wrap a TVMPackedCFunc to become a FunctionHandle. More...
 
int TVMFuncRegisterGlobal (const char *name, TVMFunctionHandle f, int override)
 Register the function to runtime's global table. More...
 
int TVMFuncGetGlobal (const char *name, TVMFunctionHandle *out)
 Get a global function. More...
 
int TVMFuncListGlobalNames (int *out_size, const char ***out_array)
 List all the globally registered function name. More...
 
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. More...
 
int TVMArrayFree (TVMArrayHandle handle)
 Free the TVM Array. More...
 
int TVMArrayCopyFromBytes (TVMArrayHandle handle, void *data, size_t nbytes)
 Copy array data from CPU byte array. More...
 
int TVMArrayCopyToBytes (TVMArrayHandle handle, void *data, size_t nbytes)
 Copy array data to CPU byte array. More...
 
int TVMArrayCopyFromTo (TVMArrayHandle from, TVMArrayHandle to, TVMStreamHandle stream)
 Copy the array, both from and to must be valid during the copy. More...
 
int TVMArrayFromDLPack (DLManagedTensor *from, TVMArrayHandle *out)
 Produce an array from the DLManagedTensor that shares data memory with the DLManagedTensor. More...
 
int TVMArrayToDLPack (TVMArrayHandle from, DLManagedTensor **out)
 Produce a DLMangedTensor from the array that shares data memory with the array. More...
 
void TVMDLManagedTensorCallDeleter (DLManagedTensor *dltensor)
 Delete (free) a DLManagedTensor's data. More...
 
int TVMStreamCreate (int device_type, int device_id, TVMStreamHandle *out)
 Create a new runtime stream. More...
 
int TVMStreamFree (int device_type, int device_id, TVMStreamHandle stream)
 Free a created stream handle. More...
 
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 will use the setted stream handle. The specific type of stream is runtime device dependent. More...
 
int TVMSynchronize (int device_type, int device_id, TVMStreamHandle stream)
 Wait until all computations on stream completes. More...
 
int TVMStreamStreamSynchronize (int device_type, int device_id, TVMStreamHandle src, TVMStreamHandle dst)
 Synchronize two streams of execution. More...
 

Macro Definition Documentation

#define TVM_VERSION   "0.6.dev"
#define TVM_WEAK   __attribute__((weak))

Typedef Documentation

typedef int64_t tvm_index_t

type of array index.

typedef DLTensor TVMArray

The tensor array stucture to TVM API.

the array handle

typedef DLContext TVMContext

The Device information, abstract away common device types.

typedef int(* TVMExtensionFuncDeclarer) (TVMFunctionHandle register_func_handle)

Signature for extension function declarer.

TVM call this function to get the extension functions The declarer will call register_func to register function and their name.

Parameters
register_func_handleThe register function
Returns
0 if success, -1 if failure happens
typedef void* TVMFunctionHandle

Handle to packed function handle.

typedef void* TVMModuleHandle

Handle to TVM runtime modules.

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

C type of packed function.

Parameters
argsThe arguments
type_codesThe type codes of the arguments
num_argsNumber of arguments.
retThe return value handle.
resource_handleThe handle additional resouce handle from fron-end.
Returns
0 if success, -1 if failure happens, set error via TVMAPISetLastError.
See also
TVMCFuncSetReturn
typedef void(* TVMPackedCFuncFinalizer) (void *resource_handle)

C callback to free the resource handle in C packed function.

Parameters
resource_handleThe handle additional resouce handle from fron-end.
typedef void* TVMRetValueHandle

Handle to hold return value.

typedef void* TVMStreamHandle

The stream that is specific to device can be NULL, which indicates the default one.

typedef DLDataType TVMType

The data type used in TVM Runtime.

Examples

  • float: type_code = 2, bits = 32, lanes=1
  • float4(vectorized 4 float): type_code = 2, bits = 32, lanes=4
  • int8: type_code = 0, bits = 8, lanes=1
Note
Arguments TVM API function always takes bits=64 and lanes=1

Enumeration Type Documentation

Extension device types in TVM.

Enumerator
kDLAOCL 
kDLSDAccel 
kOpenGL 

The type code in TVMType.

Note
TVMType is used in two places.
Enumerator
kHandle 
kNull 
kTVMType 
kTVMContext 
kArrayHandle 
kNodeHandle 
kModuleHandle 
kFuncHandle 
kStr 
kBytes 
kNDArrayContainer 
kObject 
kExtBegin 
kNNVMFirst 
kNNVMLast 
kExtReserveEnd 
kExtEnd 
kCustomBegin 

Function Documentation

void TVMAPISetLastError ( const char *  msg)

Used for implementing C API function. Set last error message before return.

Parameters
msgThe error message to be set.
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.

Parameters
shapeThe shape of the array, the data content will be copied to out
ndimThe number of dimension of the array.
dtype_codeThe type code of the dtype
dtype_bitsThe number of bits of dtype
dtype_lanesThe number of lanes in the dtype.
device_typeThe device type of context
device_idThe device id of context.
outThe output handle.
Returns
0 when success, -1 when failure happens
int TVMArrayCopyFromBytes ( TVMArrayHandle  handle,
void *  data,
size_t  nbytes 
)

Copy array data from CPU byte array.

Parameters
handleThe array handle.
datathe data pointer
nbytesThe number of bytes to copy.
Returns
0 when success, -1 when failure happens
int TVMArrayCopyFromTo ( TVMArrayHandle  from,
TVMArrayHandle  to,
TVMStreamHandle  stream 
)

Copy the array, both from and to must be valid during the copy.

Parameters
fromThe array to be copied from.
toThe target space.
streamThe stream where the copy happens, can be NULL.
Returns
0 when success, -1 when failure happens
int TVMArrayCopyToBytes ( TVMArrayHandle  handle,
void *  data,
size_t  nbytes 
)

Copy array data to CPU byte array.

Parameters
handleThe array handle.
datathe data pointer
nbytesThe number of bytes to copy.
Returns
0 when success, -1 when failure happens
int TVMArrayFree ( TVMArrayHandle  handle)

Free the TVM Array.

Parameters
handleThe array handle to be freed.
Returns
0 when success, -1 when failure happens
int TVMArrayFromDLPack ( DLManagedTensor *  from,
TVMArrayHandle out 
)

Produce an array from the DLManagedTensor that shares data memory with the DLManagedTensor.

Parameters
fromThe source DLManagedTensor.
outThe output array handle.
Returns
0 when success, -1 when failure happens
int TVMArrayToDLPack ( TVMArrayHandle  from,
DLManagedTensor **  out 
)

Produce a DLMangedTensor from the array that shares data memory with the array.

Parameters
fromThe source array.
outThe DLManagedTensor handle.
Returns
0 when success, -1 when failure happens
int TVMCbArgToReturn ( TVMValue value,
int  code 
)

Inplace translate callback argument value to return value. This is only needed for non-POD arguments.

Parameters
valueThe value to be translated.
codeThe type code to be translated.
Note
This function will do a shallow copy when necessary.
Returns
0 when success, -1 when failure happens.
int TVMCFuncSetReturn ( TVMRetValueHandle  ret,
TVMValue value,
int *  type_code,
int  num_ret 
)

Set the return value of TVMPackedCFunc.

This function is called by TVMPackedCFunc to set the return value. When this function is not called, the function returns null by default.

Parameters
retThe return value handle, pass by ret in TVMPackedCFunc
valueThe value to be returned.
type_codeThe type of the value to be returned.
num_retNumber of return values, for now only 1 is supported.
void TVMDLManagedTensorCallDeleter ( DLManagedTensor *  dltensor)

Delete (free) a DLManagedTensor's data.

Parameters
dltensorPointer to the DLManagedTensor.
int TVMExtTypeFree ( void *  handle,
int  type_code 
)

Free front-end extension type resource.

Parameters
handleThe extension handle.
type_codeThe type of of the extension type.
Returns
0 when success, -1 when failure happens
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.

Parameters
funcnode handle of the function.
arg_valuesThe arguments
type_codesThe type codes of the arguments
num_argsNumber of arguments.
ret_valThe return value.
ret_type_codethe type code of return value.
Returns
0 when success, -1 when failure happens
Note
TVM calls always exchanges with type bits=64, lanes=1
API calls always exchanges with type bits=64, lanes=1 If API call returns container handles (e.g. FunctionHandle) these handles should be managed by the front-end. The front-end need to call free function (e.g. TVMFuncFree) to free these handles.
int TVMFuncCreateFromCFunc ( TVMPackedCFunc  func,
void *  resource_handle,
TVMPackedCFuncFinalizer  fin,
TVMFunctionHandle out 
)

Wrap a TVMPackedCFunc to become a FunctionHandle.

The resource_handle will be managed by TVM API, until the function is no longer used.

Parameters
funcThe packed C function.
resource_handleThe resource handle from front-end, can be NULL.
finThe finalizer on resource handle when the FunctionHandle get freed, can be NULL
outthe result function handle.
Returns
0 when success, -1 when failure happens
int TVMFuncFree ( TVMFunctionHandle  func)

Free the function when it is no longer needed.

Parameters
funcThe function handle
Returns
0 when success, -1 when failure happens
int TVMFuncGetGlobal ( const char *  name,
TVMFunctionHandle out 
)

Get a global function.

Parameters
nameThe name of the function.
outthe result function pointer, NULL if it does not exist.
Note
The function handle of global function is managed by TVM runtime, So TVMFuncFree is should not be called when it get deleted.
int TVMFuncListGlobalNames ( int *  out_size,
const char ***  out_array 
)

List all the globally registered function name.

Parameters
out_sizeThe number of functions
out_arrayThe array of function names.
Returns
0 when success, -1 when failure happens
int TVMFuncRegisterGlobal ( const char *  name,
TVMFunctionHandle  f,
int  override 
)

Register the function to runtime's global table.

The registered function then can be pulled by the backend by the name.

Parameters
nameThe name of the function.
fThe function to be registered.
overrideWhether allow override already registered function.
const char* TVMGetLastError ( void  )

return str message of the last error all function in this file will return 0 when success and -1 when an error occured, TVMGetLastError can be called to retrieve the error

this function is threadsafe and can be called by different thread

Returns
error info
int TVMModFree ( TVMModuleHandle  mod)

Free the Module.

Parameters
modThe module to be freed.
Note
This may not free up the module's resources. If there is active TVMFunctionHandle uses the module Or if this module is imported by another active module.

The all functions remains valid until TVMFuncFree is called.

Returns
0 when success, -1 when failure happens
int TVMModGetFunction ( TVMModuleHandle  mod,
const char *  func_name,
int  query_imports,
TVMFunctionHandle out 
)

Get function from the module.

Parameters
modThe module handle.
func_nameThe name of the function.
query_importsWhether to query imported modules
outThe result function, can be NULL if it is not available.
Returns
0 when no error is thrown, -1 when failure happens
int TVMModImport ( TVMModuleHandle  mod,
TVMModuleHandle  dep 
)

Add dep to mod's dependency. This allows functions in this module to use modules.

Parameters
modThe module handle.
depThe dependent module to be imported.
Returns
0 when success, -1 when failure happens
int TVMModLoadFromFile ( const char *  file_name,
const char *  format,
TVMModuleHandle out 
)

Load module from file.

Parameters
file_nameThe file name to load the module from.
formatThe format of the module.
outThe result module
Returns
0 when success, -1 when failure happens
Note
The resulting module do not contain import relation. It can be reconstructed by TVMModImport.
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 will use the setted stream handle. The specific type of stream is runtime device dependent.

Parameters
device_typeThe device type of context
device_idThe device id of context.
handleThe stream handle.
Returns
0 when success, -1 when failure happens
int TVMStreamCreate ( int  device_type,
int  device_id,
TVMStreamHandle out 
)

Create a new runtime stream.

Parameters
device_typeThe device type of context
device_idThe device id of context
outThe new stream handle
Returns
0 when success, -1 when failure happens
int TVMStreamFree ( int  device_type,
int  device_id,
TVMStreamHandle  stream 
)

Free a created stream handle.

Parameters
device_typeThe device type of context
device_idThe device id of context
streamThe stream to be freed
Returns
0 when success, -1 when failure happens
int TVMStreamStreamSynchronize ( int  device_type,
int  device_id,
TVMStreamHandle  src,
TVMStreamHandle  dst 
)

Synchronize two streams of execution.

Parameters
device_typeThe device type of context
device_idThe device id of context
srcThe source stream to synchronize.
dstThe destination stream to synchronize.
Returns
0 when success, -1 when failure happens
int TVMSynchronize ( int  device_type,
int  device_id,
TVMStreamHandle  stream 
)

Wait until all computations on stream completes.

Parameters
device_typeThe device type of context
device_idThe device id of context.
streamThe stream to be synchronized.
Returns
0 when success, -1 when failure happens