larod.h

Go to the documentation of this file.

#ifndef COM_AXIS_LAROD_H
#define COM_AXIS_LAROD_H

#include <limits.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>

#include "larod-version.h"

#ifdef __cplusplus
extern "C" {
#endif

#ifdef LAROD_API_VERSION_1
#warning "API version 1 is deprecated and will be removed soon. " \
    "Please update to a newer API version."
#endif

#if defined(LAROD_API_VERSION_1) && defined(LAROD_API_VERSION_2)
#error API version ambiguous, specify at most one version \
    (#define LAROD_API_VERSION_*) before including larod.h
#endif

#define LAROD_TENSOR_MAX_LEN 12

#define LAROD_INVALID_MODEL_ID UINT64_MAX

#define LAROD_INVALID_FD (INT_MIN)

#define LAROD_FD_PROP_READWRITE (UINT32_C(1) << 0)
#define LAROD_FD_PROP_MAP (UINT32_C(1) << 1)
#define LAROD_FD_PROP_DMABUF (UINT32_C(1) << 2)

#define LAROD_FD_TYPE_DMA (LAROD_FD_PROP_DMABUF | LAROD_FD_PROP_MAP)
#define LAROD_FD_TYPE_DISK (LAROD_FD_PROP_READWRITE | LAROD_FD_PROP_MAP)

typedef struct larodDevice larodDevice;

#if defined(LAROD_API_VERSION_1) || defined(LAROD_API_VERSION_2) ||            \
    defined(LAROD_DOXYGEN)

typedef enum {
    LAROD_CHIP_INVALID = 0,
    LAROD_CHIP_DEBUG = 1,
    LAROD_CHIP_TFLITE_CPU = 2,
    LAROD_CHIP_TPU = 4,
    LAROD_CHIP_CVFLOW_NN = 6,
    LAROD_CHIP_TFLITE_GLGPU = 8,
    LAROD_CHIP_CVFLOW_PROC = 9,
    LAROD_CHIP_ACE = 10,
    LAROD_CHIP_LIBYUV = 11,
    LAROD_CHIP_TFLITE_ARTPEC8DLPU = 12,
    LAROD_CHIP_OPENCL = 13,
} larodChip;
#endif

typedef enum {
    LAROD_ACCESS_INVALID = 0, 
    LAROD_ACCESS_PRIVATE = 1, 
    LAROD_ACCESS_PUBLIC = 2
} larodAccess;

typedef enum {
    LAROD_ERROR_NONE = 0,
    LAROD_ERROR_JOB = -1,
#if defined(LAROD_API_VERSION_1) || defined(LAROD_DOXYGEN)
    LAROD_ERROR_INFERENCE = -1,
#endif
    LAROD_ERROR_LOAD_MODEL = -2,
    LAROD_ERROR_FD = -3,
    LAROD_ERROR_MODEL_NOT_FOUND = -4,
    LAROD_ERROR_PERMISSION = -5,
    LAROD_ERROR_CONNECTION = -6,
    LAROD_ERROR_CREATE_SESSION = -7,
    LAROD_ERROR_KILL_SESSION = -8,
    LAROD_ERROR_INVALID_CHIP_ID = -9,
    LAROD_ERROR_INVALID_ACCESS = -10,
    LAROD_ERROR_DELETE_MODEL = -11,
    LAROD_ERROR_TENSOR_MISMATCH = -12,
    LAROD_ERROR_VERSION_MISMATCH = -13,
    LAROD_ERROR_ALLOC = -14,
    LAROD_ERROR_POWER_NOT_AVAILABLE = -15,
    LAROD_ERROR_MAX_ERRNO = 1024
} larodErrorCode;

typedef enum {
    LAROD_TENSOR_DATA_TYPE_INVALID = 0, 
    LAROD_TENSOR_DATA_TYPE_UNSPECIFIED, 
    LAROD_TENSOR_DATA_TYPE_BOOL,        
    LAROD_TENSOR_DATA_TYPE_UINT8,       
    LAROD_TENSOR_DATA_TYPE_INT8,        
    LAROD_TENSOR_DATA_TYPE_UINT16,      
    LAROD_TENSOR_DATA_TYPE_INT16,       
    LAROD_TENSOR_DATA_TYPE_UINT32,      
    LAROD_TENSOR_DATA_TYPE_INT32,       
    LAROD_TENSOR_DATA_TYPE_UINT64,      
    LAROD_TENSOR_DATA_TYPE_INT64,       
    LAROD_TENSOR_DATA_TYPE_FLOAT16,     
    LAROD_TENSOR_DATA_TYPE_FLOAT32,     
    LAROD_TENSOR_DATA_TYPE_FLOAT64,     
    LAROD_TENSOR_DATA_TYPE_MAX,         
} larodTensorDataType;

typedef enum {
    LAROD_TENSOR_LAYOUT_INVALID = 0, 
    LAROD_TENSOR_LAYOUT_UNSPECIFIED, 
    LAROD_TENSOR_LAYOUT_NHWC,        
    LAROD_TENSOR_LAYOUT_NCHW,        
    LAROD_TENSOR_LAYOUT_420SP,       
    LAROD_TENSOR_LAYOUT_MAX,         
} larodTensorLayout;

typedef struct {
    larodErrorCode code; 
    const char* msg;     
} larodError;

typedef struct {
    size_t dims[LAROD_TENSOR_MAX_LEN];
    size_t len; 
} larodTensorDims;

typedef struct {
    size_t pitches[LAROD_TENSOR_MAX_LEN];
    size_t len; 
} larodTensorPitches;

typedef struct larodModel larodModel;

typedef void (*larodLoadModelCallback)(larodModel* model, void* userData,
                                       larodError* error);

typedef void (*larodRunJobCallback)(void* userData, larodError* error);

typedef struct larodConnection larodConnection;

typedef struct larodJobRequest larodJobRequest;

typedef struct larodTensor larodTensor;

typedef struct larodMap larodMap;

#if defined(LAROD_API_VERSION_1) || defined(LAROD_DOXYGEN)

typedef void (*larodRunInferenceCallback)(void* userData, larodError* error);
#endif

#if defined(LAROD_API_VERSION_1) || defined(LAROD_DOXYGEN)

typedef struct larodJobRequest larodInferenceRequest;
#endif

void larodClearError(larodError** error);

bool larodConnect(larodConnection** conn, larodError** error);

bool larodDisconnect(larodConnection** conn, larodError** error);

bool larodGetNumSessions(larodConnection* conn, uint64_t* numSessions,
                         larodError** error);

const larodDevice* larodGetDevice(const larodConnection* conn, const char* name,
                                  const uint32_t instance, larodError** error);

const char* larodGetDeviceName(const larodDevice* dev, larodError** error);

bool larodGetDeviceInstance(const larodDevice* dev, uint32_t* instance,
                            larodError** error);

#if defined(LAROD_API_VERSION_1) || defined(LAROD_API_VERSION_2)

const char* larodGetChipName(const larodChip chip);
#endif

#if defined(LAROD_API_VERSION_1) || defined(LAROD_API_VERSION_2) ||            \
    defined(LAROD_DOXYGEN)

bool larodListChips(larodConnection* conn, larodChip** chips, size_t* numChips,
                    larodError** error);
#endif

const larodDevice** larodListDevices(larodConnection* conn, size_t* numDevices,
                                     larodError** error);

#if defined(LAROD_API_VERSION_1)
larodModel* larodLoadModel_API_VERSION_1(larodConnection* conn, const int fd,
                                         const larodAccess access,
                                         const char* name, larodError** error);
#define larodLoadModel larodLoadModel_API_VERSION_1
#elif defined(LAROD_API_VERSION_2)
larodModel* larodLoadModel_API_VERSION_2(larodConnection* conn, const int fd,
                                         const larodChip chip,
                                         const larodAccess access,
                                         const char* name,
                                         const larodMap* params,
                                         larodError** error);
#define larodLoadModel larodLoadModel_API_VERSION_2
#else

larodModel* larodLoadModel(larodConnection* conn, const int fd,
                           const larodDevice* dev, const larodAccess access,
                           const char* name, const larodMap* params,
                           larodError** error);

#endif

#if defined(LAROD_API_VERSION_1)
bool larodLoadModelAsync_API_VERSION_1(larodConnection* conn, const int fd,
                                       const larodAccess access,
                                       const char* name,
                                       larodLoadModelCallback callback,
                                       void* userData, larodError** error);
#define larodLoadModelAsync larodLoadModelAsync_API_VERSION_1
#elif defined(LAROD_API_VERSION_2)
bool larodLoadModelAsync_API_VERSION_2(larodConnection* conn, const int fd,
                                       const larodChip chip,
                                       const larodAccess access,
                                       const char* name, const larodMap* params,
                                       larodLoadModelCallback callback,
                                       void* userData, larodError** error);
#define larodLoadModelAsync larodLoadModelAsync_API_VERSION_2
#else

bool larodLoadModelAsync(larodConnection* conn, const int inFd,
                         const larodDevice* dev, const larodAccess access,
                         const char* name, const larodMap* params,
                         larodLoadModelCallback callback, void* userData,
                         larodError** error);

#endif

larodModel* larodGetModel(larodConnection* conn, const uint64_t modelId,
                          larodError** error);

larodModel** larodGetModels(larodConnection* conn, size_t* numModels,
                            larodError** error);

void larodDestroyModel(larodModel** model);

void larodDestroyModels(larodModel*** models, size_t numModels);

bool larodDeleteModel(larodConnection* conn, larodModel* model,
                      larodError** error);

uint64_t larodGetModelId(const larodModel* model, larodError** error);

#if defined(LAROD_API_VERSION_2) || defined(LAROD_DOXYGEN)

larodChip larodGetModelChip(const larodModel* model, larodError** error);
#endif

const larodDevice* larodGetModelDevice(const larodModel* model,
                                       larodError** error);

size_t larodGetModelSize(const larodModel* model, larodError** error);

const char* larodGetModelName(const larodModel* model, larodError** error);

larodAccess larodGetModelAccess(const larodModel* model, larodError** error);

size_t larodGetModelNumInputs(const larodModel* model, larodError** error);

size_t larodGetModelNumOutputs(const larodModel* model, larodError** error);

size_t* larodGetModelInputByteSizes(const larodModel* model, size_t* numInputs,
                                    larodError** error);

size_t* larodGetModelOutputByteSizes(const larodModel* model,
                                     size_t* numOutputs, larodError** error);

larodTensor** larodCreateModelInputs(const larodModel* model,
                                     size_t* numTensors, larodError** error);

larodTensor** larodCreateModelOutputs(const larodModel* model,
                                      size_t* numTensors, larodError** error);

larodTensor** larodAllocModelInputs(larodConnection* conn,
                                    const larodModel* model,
                                    const uint32_t fdPropFlags,
                                    size_t* numTensors, larodMap* params,
                                    larodError** error);

larodTensor** larodAllocModelOutputs(larodConnection* conn,
                                     const larodModel* model,
                                     const uint32_t fdPropFlags,
                                     size_t* numTensors, larodMap* params,
                                     larodError** error);

larodTensor** larodCreateTensors(size_t numTensors, larodError** error);

#if defined(LAROD_API_VERSION_1) || defined(LAROD_API_VERSION_2)
void larodDestroyTensors_API_VERSION_1(larodTensor*** tensors,
                                       size_t numTensors);
#define larodDestroyTensors larodDestroyTensors_API_VERSION_1
#else

bool larodDestroyTensors(larodConnection* conn, larodTensor*** tensors,
                         size_t numTensors, larodError** error);
#endif

bool larodSetTensorDims(larodTensor* tensor, const larodTensorDims* dims,
                        larodError** error);

const larodTensorDims* larodGetTensorDims(const larodTensor* tensor,
                                          larodError** error);

bool larodSetTensorPitches(larodTensor* tensor,
                           const larodTensorPitches* pitches,
                           larodError** error);

const larodTensorPitches* larodGetTensorPitches(const larodTensor* tensor,
                                                larodError** error);

bool larodSetTensorDataType(larodTensor* tensor,
                            const larodTensorDataType dataType,
                            larodError** error);

larodTensorDataType larodGetTensorDataType(const larodTensor* tensor,
                                           larodError** error);

bool larodSetTensorLayout(larodTensor* tensor, const larodTensorLayout layout,
                          larodError** error);

larodTensorLayout larodGetTensorLayout(const larodTensor* tensor,
                                       larodError** error);

bool larodSetTensorFd(larodTensor* tensor, const int fd, larodError** error);

int larodGetTensorFd(const larodTensor* tensor, larodError** error);

bool larodSetTensorFdSize(larodTensor* tensor, const size_t size,
                          larodError** error);

bool larodGetTensorFdSize(const larodTensor* tensor, size_t* size,
                          larodError** error);

bool larodSetTensorFdOffset(larodTensor* tensor, const int64_t offset,
                            larodError** error);

int64_t larodGetTensorFdOffset(const larodTensor* tensor, larodError** error);

bool larodTrackTensor(larodConnection* conn, larodTensor* tensor,
                      larodError** error);

bool larodSetTensorFdProps(larodTensor* tensor, const uint32_t fdPropFlags,
                           larodError** error);

bool larodGetTensorFdProps(const larodTensor* tensor, uint32_t* fdPropFlags,
                           larodError** error);

const char* larodGetTensorName(const larodTensor* tensor, larodError** error);

bool larodGetTensorByteSize(const larodTensor* tensor, size_t* byteSize,
                            larodError** error);

larodMap* larodCreateMap(larodError** error);

void larodDestroyMap(larodMap** map);

bool larodMapSetStr(larodMap* map, const char* key, const char* value,
                    larodError** error);

bool larodMapSetInt(larodMap* map, const char* key, const int64_t value,
                    larodError** error);

bool larodMapSetIntArr2(larodMap* map, const char* key, const int64_t value0,
                        const int64_t value1, larodError** error);

bool larodMapSetIntArr4(larodMap* map, const char* key, const int64_t value0,
                        const int64_t value1, const int64_t value2,
                        const int64_t value3, larodError** error);

const char* larodMapGetStr(larodMap* map, const char* key, larodError** error);

bool larodMapGetInt(larodMap* map, const char* key, int64_t* value,
                    larodError** error);

const int64_t* larodMapGetIntArr2(larodMap* map, const char* key,
                                  larodError** error);

const int64_t* larodMapGetIntArr4(larodMap* map, const char* key,
                                  larodError** error);

larodJobRequest* larodCreateJobRequest(const larodModel* model,
                                       larodTensor** inputTensors,
                                       size_t numInputs,
                                       larodTensor** outputTensors,
                                       size_t numOutputs, larodMap* params,
                                       larodError** error);

void larodDestroyJobRequest(larodJobRequest** jobReq);

bool larodSetJobRequestModel(larodJobRequest* jobReq, const larodModel* model,
                             larodError** error);

bool larodSetJobRequestInputs(larodJobRequest* jobReq, larodTensor** tensors,
                              const size_t numTensors, larodError** error);

bool larodSetJobRequestOutputs(larodJobRequest* jobReq, larodTensor** tensors,
                               const size_t numTensors, larodError** error);

bool larodSetJobRequestPriority(larodJobRequest* jobReq, const uint8_t priority,
                                larodError** error);

bool larodSetJobRequestParams(larodJobRequest* jobReq, const larodMap* params,
                              larodError** error);

bool larodRunJob(larodConnection* conn, const larodJobRequest* jobReq,
                 larodError** error);

bool larodRunJobAsync(larodConnection* conn, const larodJobRequest* jobReq,
                      larodRunJobCallback callback, void* userData,
                      larodError** error);

#ifdef LAROD_DOXYGEN
// The following declaration is only for documentation purposes. Not to be used
// in actual code.
larodModel* larodLoadModel(larodConnection* conn, const int fd,
                           const larodAccess access, const char* name,
                           larodError** error);
#endif

#ifdef LAROD_DOXYGEN
// The following declaration is only for documentation purposes. Not to be used
// in actual code.
larodModel* larodLoadModel(larodConnection* conn, const int fd,
                           const larodChip chip, const larodAccess access,
                           const char* name, const larodMap* params,
                           larodError** error);
#endif

#ifdef LAROD_DOXYGEN
// The following declaration is only for documentation purposes. Not to be used
// in actual code.
bool larodLoadModelAsync(larodConnection* conn, const int fd,
                         const larodAccess access, const char* name,
                         larodLoadModelCallback callback, void* userData,
                         larodError** error);
#endif

#ifdef LAROD_DOXYGEN
// The following declaration is only for documentation purposes. Not to be used
// in actual code.
bool larodLoadModelAsync(larodConnection* conn, const int fd,
                         const larodChip chip, const larodAccess access,
                         const char* name, const larodMap* params,
                         larodLoadModelCallback callback, void* userData,
                         larodError** error);
#endif

#if defined(LAROD_API_VERSION_1) || defined(LAROD_DOXYGEN)

larodInferenceRequest* larodCreateInferenceRequest(
    const larodModel* model, larodTensor** inputTensors, size_t numInputs,
    larodTensor** outputTensors, size_t numOutputs, larodError** error);
#endif

#if defined(LAROD_API_VERSION_1) || defined(LAROD_DOXYGEN)

void larodDestroyInferenceRequest(larodInferenceRequest** infReq);
#define larodDestroyInferenceRequest larodDestroyJobRequest
#endif

#if defined(LAROD_API_VERSION_1) || defined(LAROD_DOXYGEN)

bool larodSetInferenceRequestModel(larodInferenceRequest* infReq,
                                   const larodModel* model, larodError** error);
#define larodSetInferenceRequestModel larodSetJobRequestModel
#endif

#if defined(LAROD_API_VERSION_1) || defined(LAROD_DOXYGEN)

bool larodSetInferenceRequestInputs(larodInferenceRequest* infReq,
                                    larodTensor** tensors,
                                    const size_t numTensors,
                                    larodError** error);
#define larodSetInferenceRequestInputs larodSetJobRequestInputs
#endif

#if defined(LAROD_API_VERSION_1) || defined(LAROD_DOXYGEN)

bool larodSetInferenceRequestOutputs(larodInferenceRequest* infReq,
                                     larodTensor** tensors,
                                     const size_t numTensors,
                                     larodError** error);
#define larodSetInferenceRequestOutputs larodSetJobRequestOutputs
#endif

#if defined(LAROD_API_VERSION_1) || defined(LAROD_DOXYGEN)

bool larodSetInferenceRequestPriority(larodInferenceRequest* infReq,
                                      const uint8_t priority,
                                      larodError** error);
#define larodSetInferenceRequestPriority larodSetJobRequestPriority
#endif

#if defined(LAROD_API_VERSION_1) || defined(LAROD_DOXYGEN)

bool larodRunInference(larodConnection* conn,
                       const larodInferenceRequest* infReq, larodError** error);
#endif

#if defined(LAROD_API_VERSION_1) || defined(LAROD_DOXYGEN)

bool larodRunInferenceAsync(larodConnection* conn,
                            const larodInferenceRequest* infReq,
                            larodRunInferenceCallback callback, void* userData,
                            larodError** error);
#endif

#if defined(LAROD_API_VERSION_2) || defined(LAROD_DOXYGEN)
bool larodRunJobAsync_API_VERSION_2(larodConnection* conn,
                                    const larodJobRequest* jobReq,
                                    larodRunJobCallback callback,
                                    void* userData, larodError** error);
#define larodRunJobAsync larodRunJobAsync_API_VERSION_2
#endif

#if defined(LAROD_API_VERSION_2) || defined(LAROD_DOXYGEN)
bool larodRunJob_API_VERSION_2(larodConnection* conn,
                               const larodJobRequest* jobReq,
                               larodError** error);
#define larodRunJob larodRunJob_API_VERSION_2
#endif

#if defined(LAROD_API_VERSION_1) || defined(LAROD_DOXYGEN)

bool larodGetChipId(larodConnection* conn, uint64_t* chipId,
                    larodError** error);
#endif

#if defined(LAROD_API_VERSION_1) || defined(LAROD_DOXYGEN)

bool larodSetChipId(larodConnection* conn, const uint64_t chipId,
                    larodError** error);
#endif

#if defined(LAROD_API_VERSION_1) || defined(LAROD_DOXYGEN)

bool larodSetChip(larodConnection* conn, const larodChip chip,
                  larodError** error);
#endif

#if defined(LAROD_API_VERSION_1) || defined(LAROD_DOXYGEN)

bool larodGetChipType(larodConnection* conn, larodChip* chipType,
                      larodError** error);
#endif

#if defined(LAROD_DOXYGEN)

void larodDestroyTensors(larodTensor*** tensors, size_t numTensors);
#endif

#ifdef __cplusplus
}
#endif

#endif // COM_AXIS_LAROD_H