calculet-npu-research-archive/source/baseline-expanded/calrt-sdk-0.7.6/usr/local/include/calrt/calrt.h

#ifndef _CALRT_H_
#define _CALRT_H_

/**
 * @brief an interface for c file
 * 
 */

#ifdef __cplusplus
extern "C" {
#endif

#include <stdint.h>
#include <stddef.h>

#include "calrt_platform.h"
#include "calrt_error.h"

#define CAL_MAX_FILE_PATH (128)
#define CAL_MAX_NAME (256)

// ---------------------------------------- enum --------------------------------------

typedef enum _CalrtDeviceType_e
{
    UNDEFINE_TYPE = 0,
    PCIE = 1,
    USB,
    EMU
}cal_device_type_e;

typedef enum _CalrtTransDirection_e
{
    HOST_TO_DEVICE = 0,
    DEVICE_TO_HOST
}cal_direction_e;

typedef enum _CalrtPowerMode_e
{
    BALANCE = 1,
    HIGH_PERFORMANCE = 2
}cal_power_e;

// ---------------------------------------- struct --------------------------------------

typedef struct _CalrtDeviceId_t
{
    cal_device_type_e dev_type;
    char path[CAL_MAX_FILE_PATH];
}cal_device_id_t;

typedef struct _CalrtDeviceInfo_t
{
    cal_device_id_t id;
    char name[CAL_MAX_NAME];
    uint64_t ddr_size;
    float sram_freq_mhz;
    float sram_size_mb;
}cal_device_info_t;

typedef struct _CalrtModel_t
{
    char name[CAL_MAX_NAME];
}cal_model_t;

typedef struct _CalrtTensor_t
{
    uint64_t size;
    uint64_t element_num;
    uint64_t *shape;
    int shape_dim; // indicate shape length
}cal_tensor_info_t;

// ---------------------------------------- pre-declare struct --------------------------------------

typedef struct _Calrt_Calbin *cal_calbin;
typedef struct _Calrt_Dev *cal_device;
typedef struct _Calrt_InputBuf *cal_ibuffer;
typedef struct _Calrt_OutputBuf *cal_obuffer;
typedef struct _Calrt_Tensor *cal_tensor;


// ---------------------------------------- Calbin ----------------------------------------

/**
 * @brief Create a calbin object
 * 
 * @param calbin calbin struct
 * @param calbin_path path to calbin file
 * @return CalrtError_e 0 on success
 */
CALRT_API CalrtError_e create_calbin(cal_calbin *calbin, const char* calbin_path);

/**
 * @brief Get the all models object
 * 
 * @param calbin 
 * @return int the number of models inside calbin
 */
CALRT_API int get_models_number(cal_calbin calbin);

/**
 * @brief Get the all models name
 * 
 * @param model_num the size of models name list
 * @param name model name list
 * @return CalrtError_e CalrtSuccess on success(0)
 */
CALRT_API CalrtError_e get_all_models(int model_num, char** name, cal_calbin calbin);

CALRT_API void print_calbin(cal_calbin calbin);

// ---------------------------------------- Device ----------------------------------------

/**
 * @brief Create a pcie device object
 * 
 * @param device 
 * @return CalrtSuccess on success(0)
 */
CALRT_API CalrtError_e create_device(cal_device *device);

/**
 * @brief Create a device by type object
 * 
 * @param device cal_device
 * @param type device type
 * @return CalrtError_e 
 */
CALRT_API CalrtError_e create_device_by_type(cal_device *device, cal_device_type_e type);

CALRT_API void reset_device_configuration(cal_device device);

CALRT_API void reset_device(cal_device device);

// ---------------------------------------- Buffer ----------------------------------------

/**
 * @brief Create a input buffer object
 * 
 * @param buffer 
 * @param calbin
 * @return CalrtError_e 0 on success
 */
CALRT_API CalrtError_e create_input_buffer(cal_ibuffer *buffer, cal_calbin calbin, const char* model_name);

/**
 * @brief Create a output buffer object
 * 
 * @param buffer 
 * @param calbin
 * @return CalrtError_e CalrtSuccess on success(0)
 */
CALRT_API CalrtError_e create_output_buffer(cal_obuffer *buffer, cal_calbin calbin, const char* model_name);

/**
 * @brief Get the input tensor number
 * 
 * @param buffer input buffer
 * @return the amount of tensors
 */
CALRT_API int get_input_tensor_num(cal_ibuffer buffer);

/**
 * @brief Get the output tensor number
 * 
 * @param buffer output buffer
 * @return the amount of tensors
 */
CALRT_API int get_output_tensor_num(cal_obuffer buffer);

/**
 * @brief Get the input tensor by name
 * 
 * @param buffer input buffer struct
 * @param name tensor name
 * @param tensor cal_tensor
 * @return CalrtSuccess on success(0) 
 */
CALRT_API CalrtError_e get_input_tensor_by_name(cal_ibuffer buffer, const char* name, cal_tensor *tensor);

/**
 * @brief Get the output tensor by name
 * 
 * @param buffer output buffer struct
 * @param name tensor name
 * @param tensor 
 * @return CalrtSuccess on success(0)
 */
CALRT_API CalrtError_e get_output_tensor_by_name(cal_obuffer buffer, const char* name, cal_tensor *tensor);

/**
 * @brief Set the csr value by name
 * 
 * @param buffer 
 * @param name 
 * @param value 
 */
CALRT_API void set_csr_by_name(cal_ibuffer buffer, const char* name, uint32_t value);

/**
 * @brief Get the csr value by name
 * 
 * @param buffer 
 * @param name 
 * @return value 
 */
CALRT_API uint32_t get_csr_value_by_name(cal_ibuffer buffer, const char* name);

CALRT_API cal_tensor_info_t get_tensor_info(cal_tensor tensor);

// ---------------------------------------- Inference ----------------------------------------

/**
 * @brief blocking inference interface
 * 
 * @param device 
 * @param model_name 
 * @param calbin 
 * @param inputBuffer 
 * @param outputBuffer 
 */
CALRT_API void block_infer_model(cal_device device, const char* model_name, cal_calbin calbin, cal_ibuffer inputBuffer, cal_obuffer outputBuffer);

/**
 * @brief non-blocking inference interface
 * 
 * @param device 
 * @param model_name 
 * @param calbin 
 * @param inputBuffer 
 * @param outputBuffer 
 */
CALRT_API void non_block_infer_model(cal_device device, const char* model_name, cal_calbin calbin, cal_ibuffer inputBuffer, cal_obuffer outputBuffer);

/**
 * @brief co-op with non_block_infer_model api
 * 
 * @param outputBuffer 
 * @return CalrtSuccess on success(0)
 */
CALRT_API CalrtError_e wait_infer_done(cal_obuffer outputBuffer);

// ---------------------------------------- Configure ----------------------------------------

/**
 * @brief configure calbin into the current device
 * 
 * @param device 
 * @param calbin 
 * @return CalrtSuccess on success(0)
 */
CALRT_API CalrtError_e configure_device(cal_device device, cal_calbin calbin);

// ---------------------------------------- Memory Management ----------------------------------------

/**
 * @brief copy host data to device. tensor MUST be input tensor
 * @warning user must guarantee tensor is from input buffer
 * 
 * @param host host side buffer
 * @param tensor
 * @param size byte
 */
CALRT_API CalrtError_e cal_copy_mem(void *host, cal_tensor tensor, uint64_t size, cal_direction_e direction);

/**
 * @brief safer way to copy host data to device.
 * 
 * @param host host side buffer
 * @param size byte
 * @param buffer input buffer
 * @param name tensor name
 * @param offset the location where to write data in device memory
 * @return CalrtSuccess on success(0)
 */
CALRT_API CalrtError_e copy_mem_to_device_by_tensor_name(void *host, cal_ibuffer ibuffer, uint64_t size, const char* name, uint64_t offset=0);

/**
 * @brief safer way to copy device data to host. tensor must be output tensor
 * 
 * @param host host side buffer
 * @param size byte
 * @param buffer output buffer
 * @param name tensor name
 * @param offset the location where to read data in device memory
 */
CALRT_API CalrtError_e copy_mem_to_host_by_tensor_name(void *host, cal_obuffer obuffer, uint64_t size, const char* name, uint64_t offset=0);

// ---------------------------------------- Resource Release ----------------------------------------

CALRT_API void release_device(cal_device device);
CALRT_API void release_calbin(cal_calbin calbin);
CALRT_API void release_input_buffer(cal_ibuffer buffer);
CALRT_API void release_output_buffer(cal_obuffer buffer);
CALRT_API void release_tensor_info(cal_tensor_info_t &tensor_info);

#ifdef __cplusplus  
}
#endif

#endif /*_CALRT_H_*/