Kneron NPU Host API

Host API is the API to setup communication channels between host (such as PC, Embedded Chips) and Kneron NPU Chip. Users can use Host API to write programs that utilize low power and high performance Kneron NPU Chip to accelarate their deep learning model application. There are three types of APIs:

Include Header File: kdp_host.h


Defines

Define Value Description
KDP_UART_DEV 0 identification of using UART I/F
KDP_USB_DEV 1 identification of using USB I/F
IMG_FORMAT_RGBA8888 0x80000000 image format: RGBA8888
IMG_FORMAT_RAW8 0x80000020 image format: RAW8
IMG_FORMAT_YCbCr422 0x80000037 image format: YCbCr422 [low byte]Y0CbY1CrY2CbY3Cr...[high byte]
IMG_FORMAT_RGB565 0x80000060 image foramt: RGB565
DEF_FR_THRESH FID_THRESHOLD FDR app only, default face recognition threshold
DEF_RGB_FR_THRESH DEF_FR_THRESH FDR app only, default face recognition threshold for RGB source
DEF_NIR_FR_THRESH DEF_FR_THRESH FDR app only, default face recognition threshold for NIR soruce
DEFAULT_CONFIG BIT0 ISI Start cmd flags: use default configuration
DOWNLOAD_MODEL BIT1 ISI Start cmd flags: download model
CONFIG_USE_FLASH_MODEL BIT0 ISI Config parameters: 1: use flash model, 0: use model in memory
FLAGS_RETRIEVE_NPU_INPUT_MEM BIT0 ISI Retrieve cmd flags: debug use only, dump model input memory
FLAGS_RETRIEVE_NPU_OUPUT_MEM BIT1 ISI Retrieve cmd flags: debug use only, dump model output memory
FLAGS_RETRIEVE_WORKING_BUFFER BIT2 ISI Retrieve cmd flags: debug use only, dump model working buffer
FLAGS_PARAMS_HAS_CROP BIT0 image_params[0/1/2/3]: cropping top/bottom/left/right
FLAGS_PARAMS_HAS_PAD BIT1 image_params[n..n+3]: padding top/bottom/left/right
FLAGS_PARAMS_HAS_POST_PROC_PARAMS (BIT2 | BIT3 | BIT4 | BIT5 | BIT6 | BIT7) Length of post processing parameters
FLAGS_POST_PROC_PARAMS_BIT_POS (2) Post proc parameter length position. image_params[n..n+len-1] is for post-proc
FLAGS_PARAMS_HAS_EXT_LEN (BIT16 | BIT17 | BIT18 | BIT19 | BIT20 | BIT21 | BIT22 | BIT23) Length of extended parameters
FLAGS_EXT_LEN_BIT_POS (16) Extended parameter length position. image_params[n..n+ext_len-1] is model specific
HICO_RESULTS_SEL_IMG BIT0 HICO results select: image
HICO_FLAGS_LOOP_BACK BIT0 HICO flags: camera loopback
HICO_FLAGS_MODEL_IN_FLASH BIT1 HICO flags: use model in flash
HICO_FLAGS_FAKE_INFERENCE BIT2 HICO flags: use fake inference

Enumerations

kdp_product_id_e

enum kdp_product_id_e {...}

enum for USD PID(Product ID)

Enumerator
KDP_DEVICE_KL520 = 0x100, USB PID alias for KL520
KDP_DEVICE_KL720 = 0x200, USB PID alias for KL720

kdp_usb_speed_e

enum kdp_usb_speed_e {...}

enum for USB speed mode

Enumerator
KDP_USB_SPEED_UNKNOWN = 0, unknown USB speed
KDP_USB_SPEED_LOW = 1, USB low speed
KDP_USB_SPEED_FULL = 2, USB full speed
KDP_USB_SPEED_HIGH = 3, USB high speed
KDP_USB_SPEED_SUPER = 4, USB super speed

Structs

hico_results_t

typedef struct hico_results_t {...}

HICO result structure element

Members
bounding_box_t bounding_box; Object bounding box
motion_vector_t vectors; Object motion vector

kapp_hico_results_s

struct kapp_hico_results_s {...}

HICO result structure

Members
uint32_t seq_num; Image sequence number
uint32_t image_size; Image size
uint16_t flags; Result flags
uint16_t results_count; Result count
hico_results_t results[1]; Results

kapp_isi_data_s

struct kapp_isi_data_s {...}

ISI data

Members
uint32_t size; Size of this struct and m[]
uint32_t version; Version
uint32_t output_size; result buffer size allocated
uint32_t config_block; # of config blocks (max = 4)
struct kapp_isi_model_cfg_s m[]; model specific config data

kapp_isi_model_cfg_s

struct kapp_isi_model_cfg_s {...}

ISI START configuration data structure

Members
uint32_t model_id; Model ID
struct kdp_img_desc img; Image descriptor
uint32_t ext_param[MAX_PARAMS_LEN]; Extended parameters

kdp_db_config_s

struct kdp_db_config_s {...}

FDR App only, DB configuration structure

Members
uint16_t db_num; number of database
uint16_t max_uid; max number of user ID in each db
uint16_t max_fid; max number of feature map

kdp_device_info_list_s

struct kdp_device_info_list_s {...}

Information structure of connected devices

Members
int num_dev; connnected devices
kdp_device_info_t kdevice[1]; real index range from 0 ~ (num_dev-1)

kdp_device_info_s

struct kdp_device_info_s {...}

Device information structure

Members
int scan_index; scanned order index, can be used by kdp_connect_usb_device()
bool isConnectable; indicate if this device is connectable
unsigned short vendor_id; supposed to be 0x3231
unsigned short product_id; for kdp_product_id_e
int link_speed; for kdp_usb_speed_e
unsigned int serial_number; KN number
char device_path[20]; "busNo-hub_portNo-device_portNo"
ex: "1-2-3", means bus 1 - (hub) port 2 - (device) port 3

kdp_dme_cfg_s

struct kdp_dme_cfg_s {...}

DME image configuration structure

Members
int32_t model_id; Model indentification ID
int32_t output_num; Output number
int32_t image_col; Column size.
NIR8: must be multiple of 4;
RGB565/YCBCR422: must be multiple of 2.
int32_t image_row; Row size
int32_t image_ch; Channel size
uint32_t image_format; Image format
struct kdp_crop_box_s crop_box; y1, y2, x1, x2, for future use
struct kdp_pad_value_s pad_values; for future use
float ext_param[MAX_PARAMS_LEN]; extra parameters, such as threshold

kdp_fid_fd_s

struct kdp_fid_fd_s {...}

FID FD result structure

Members
uint16_t x; X-coordinate
uint16_t y; Y-coordinate
uint16_t w; Width
uint16_t h; Height
uint16_t class_num; Class number

kdp_fid_fr_s

struct kdp_fid_fr_s {...}

FID FR result structure

Members
float fm[FR_FEAT_SIZE]; Feature map

kdp_fid_lm_s

struct kdp_fid_lm_s {...}

FID LM 5-point result structure

Members
kdp_fid_point_t marks[LAND_MARK_POINTS]; Landmarks

kdp_fid_point_t

typedef struct kdp_fid_point_t {...}

FID point structure

Members
uint16_t x; X-coordinate
uint16_t y; Y-coordinate

kdp_hico_cfg_s

struct kdp_hico_cfg_s {...}

HICO configuration structure

Members
uint32_t app_id; Application id
uint32_t res_buf_size; Result buffer size
uint16_t results_sel; Results select
uint16_t camera_sel; Camera select
uint16_t image_col; Image pixel column
uint16_t image_row; Image pixel row
uint32_t image_format; Image format
uint32_t model_id; Model ID
uint32_t flags; control flags
uint16_t params[MAX_PARAMS_LEN * 2]; parameters, such as threshold

kdp_isi_cfg_s

struct kdp_isi_cfg_s {...}

ISI image configuration structure

Members
uint32_t app_id; Application id
uint32_t res_buf_size; Result buffer size
uint16_t image_col; Column size.
NIR8: must be multiple of 4;
RGB565/YCBCR422: must be multiple of 2.
uint16_t image_row; row size
uint32_t image_format; image format
float ext_param[MAX_PARAMS_LEN]; extra parameters, such as threshold

kdp_isi_image_header_s

struct kdp_isi_image_header_s {...}

ISI image header structure

Members
uint32_t image_length; Image length in bytes
uint32_t image_seq_num; Image sequence number
uint16_t image_col; Image pixel column
uint16_t image_row; Image pixel row
uint32_t image_format; Image format
uint32_t model_id; Model ID
uint32_t flags; Flags for using variable size of image_params[]
uint16_t image_params[1]; Image processing parameters in units of u16 - variable size

kdp_isi_start_s

struct kdp_isi_start_s {...}

ISI START Command API structure

Members
uint32_t app_id; Application ID
uint32_t compatible_cfg; =0 (non 0 for old usage)
uint32_t start_flag; Control flags
struct kapp_isi_data_s config; Configuration data

kdp_metadata_s

struct kdp_metadata_s {...}

Metadata for nef model data: metadata / fw_info / all_models

Members
char platform[32]; usb dongle, 96 board, etc.
uint32_t target; 0: KL520, 1: KL720, etc.
uint32_t crc; CRC value for all_models data
uint32_t kn_num; KN number
uint32_t enc_type; encrypt type
char tc_ver[32]; toolchain version
char compiler_ver[32]; compiler version

kdp_nef_info_s

struct kdp_nef_info_s {...}

NEF info for nef model data: metadata / fw_info / all_models

Members
char* fw_info_addr; Address of fw_info part
uint32_t fw_info_size; Size of fw_info part
char* all_models_addr; Address of all_model part
uint32_t all_models_size; Size of all_model part

ld_post_params_t

typedef struct ld_post_params_t {...}

Car license detection post-proc parameter structure

Members
float prob_thresh; Probability threshold
float nms_thresh; NMS threshold

od_post_params_t

typedef struct od_post_params_t {...}

Object Detection class post process params

Members
float prob_thresh; Probability threshold
float nms_thresh; NMS threshold
uint32_t max_detection_per_class; Max objects to detect per class
uint16_t anchor_row; Row number of anchors
uint16_t anchor_col; Colomn number of anchors
uint16_t stride_size; Stride size
uint16_t reserved_size; Reserved
uint32_t data[MAX_PARAMS_LEN - 5]; Data to hold optional anchors/stride/etc

pd_post_params_t

typedef struct pd_post_params_t {...}

Car plate detection post-proc parameter structure

Members
float lp_thresh; Plate detection threshold
float crop_top_left_x; Top-left crop X-coordinate
float crop_top_left_y; Top-left crop Y-coordinate
float dratio_w; Dratio width
float dratio_h; Dratio height

Unions

kapp_db_config_parameter_u

union kapp_db_config_parameter_u {...}

FDR App only, DB config parameter union #total [8 Bytes] (32-bits auto align)

Members
kdp_db_config_t db_config; kdp_db_config_t [6 Bytes]
uint32_t uint32_value; config uint32_t parameter [4 Bytes]

Functions

kdp_add_dev

To add com device to the host lib

int kdp_add_dev(
    int type
    const char* name
)
Parameters:

type            [in]      device type, only KDP_USB_DEV is supported now
name            [in]      the UART device name

Returns:

'dev idx' on succeed, -1 on failure


kdp_connect_usb_device

To connect to a Kneron device via the 'scan_index'

int kdp_connect_usb_device(
    int scan_index
)
Parameters:

scan_index      [in]      the dev_idx to connect.
                          value starts from 1, can be retrieved through kdp_scan_devices()

Returns:

'dev_idx' if connection is established, '< 0' means connection is not established,


kdp_dme_configure

To request for configuring dme

int kdp_dme_configure(
    int dev_idx
    char* data
    int dat_size
    uint32_t* ret_model_id
)
Parameters:

dev_idx         [in]      connected device ID
data            [in]      inference setup data
dat_size        [in]      the size of setup data
ret_model_id    [out]     the return value of model id for this configuration

Returns:

0 on succeed, error code on failure


kdp_dme_get_status

To request for getting DME inference status

int kdp_dme_get_status(
    int dev_idx
    uint16_t *ssid
    uint16_t *status
    uint32_t* inf_size
    char* inf_res
)
Parameters:

dev_idx         [in]      connected device ID
ssid            [out]     ssid to get inference status
status          [out]     inference status, 0 for not ready, 1 for ready
inf_size        [out]     inference data size
inf_res         [out]     inference result data

Returns:

0 on succeed, error code on failure


kdp_dme_inference

To do inference with provided model

int kdp_dme_inference(
    int dev_idx
    char* img_buf
    int buf_len
    uint32_t* inf_size
    bool* res_flag
    char* inf_res
    uint16_t mode
    uint16_t model_id
)
Parameters:

dev_idx         [in]      connected device ID
img_buf         [in]      the image buffer
buf_len         [in]      the buffer size
inf_size        [in]      the size of inference result in DME 'serial mode'
                          the session id of the image in DME 'async mode'
res_flag        [out]     indicate whether result is requested and available
inf_res         [out]     contains the returned inference result
mode            [in]      running mode: 0:'serial' or 1: 'async mode'
model_id        [in]      the model id for this configuration

Returns:

0 on succeed, error code on failure

Notes:

Must call kdp_start_dme() and kdp_dme_configure() to configure the dme model.


kdp_dme_retrieve_res

To request for retrieving DME result

int kdp_dme_retrieve_res(
    int dev_idx
    uint32_t addr
    int len
    char* inf_res
)
Parameters:

dev_idx         [in]      connected device ID
addr            [in]      the ddr address to retrieve
len             [in]      the size of data to retrieve
inf_res         [out]     contains the retrieving result

Returns:

0 on succeed, error code on failure


kdp_end_dme

request for ending dme mode

int kdp_end_dme(
    int dev_idx
)
Parameters:

dev_idx         [in]      connected device ID

Returns:

0 on succeed, error code on failure


kdp_end_hico

request for ending HICO mode

int kdp_end_hico(
    int dev_idx
    uint32_t param
    uint32_t* rsp_code
)
Parameters:

dev_idx         [in]      connected device ID

Returns:

0 on succeed, error code on failure


kdp_end_isi

request for ending isi mode

int kdp_end_isi(
    int dev_idx
)
Parameters:

dev_idx         [in]      connected device ID

Returns:

0 on succeed, error code on failure


kdp_export_db

To export from DB image from device

int kdp_export_db(
    int dev_idx
    char **p_buf
    uint32_t *p_len
)
Parameters:

dev_idx         [in]      connected device ID
p_buf           [out]     an output pointer for the allocated memory with the exported DB
p_len           [out]     DB size

Returns:

0 on succeed, error code on failure

Notes:


kdp_extract_feature_generic

To extract face feature from image with specified output mask

int kdp_extract_feature_generic(
    int dev_idx
    char* img_buf
    int buf_len
    uint16_t* mask
    char* res
)
Parameters:

dev_idx         [in]      connected device ID
img_buf         [in]      the image buffere
buf_len         [in]      the image buffer size
mask            [in,out]  input:indicate the mask of requested data, output:updated mask
res             [out]     preallocated memory for the specified output
                          call kdp_get_res_size() to get result size

Returns:

0 on succeed, error code on failure

Notes:


kdp_fm_compare

Calculate similarity of two feature points

float kdp_fm_compare(
    float *user_fm_a
    float *user_fm_b
    size_t fm_size
)
Parameters:

user_fm_a       [in]      buffer A of user feature map data
user_fm_b       [in]      buffer B of user feature map data
fm_size         [in]      size of user feature map data

Returns:

similarity score: smaller score meas more similar errcode -1:parameter error

Notes:

must ensure buffer A and B are the same size


kdp_get_crc

To request for CRC info of models in DDR or Flash

int kdp_get_crc(
    int dev_idx
    int from_ddr
    char *data_buf
)
Parameters:

dev_idx         [in]      connected device ID. A host can connect several devices
from_ddr        [in]      query models in ddr (1) or flash (0)
data_buf        [out]     the pointer to store crc

Returns:

0 on succeed, -1 on failure


kdp_get_db_config

Get DB structure configuration

int kdp_get_db_config(
    int dev_idx
    kdp_db_config_t* db_config
)
Parameters:

dev_idx         [in]      connected device ID
db_config       [out]     return configuration data

Returns:

0 on succeed, error code on failure

Notes:


kdp_get_db_index

Get current DB index

int kdp_get_db_index(
    int dev_idx
    uint32_t *db_idx
)
Parameters:

dev_idx         [in]      connected device ID
db_idx          [out]     return current DB index

Returns:

current DB index

Notes:


kdp_get_db_meta_data_version

get DB meta data version number for DB schema confirmation

int kdp_get_db_meta_data_version(
    int dev_idx
    uint32_t *db_meta_data_version
)
Parameters:

dev_idx         [in]      connected device ID
db_meta_data_version[out]     return DB meta data version number

Returns:

0 on succeed, error code on failure

Notes:


kdp_get_db_version

Get DB version number

int kdp_get_db_version(
    int dev_idx
    uint32_t *db_version
)
Parameters:

dev_idx         [in]      connected device ID
db_version      [out]     return DB version number

Returns:

0 on succeed, error code on failure

Notes:


kdp_get_kn_number

To request for device KN number

int kdp_get_kn_number(
    int dev_idx
    uint32_t *kn_num
)
Parameters:

dev_idx         [in]      connected device ID.
kn_num          [in]      the pointer to store KN number

Returns:

0 on succeed, -1 on failure


kdp_get_model_info

To request model IDs information for models in DDR or Flash

int kdp_get_model_info(
    int dev_idx
    int from_ddr
    char *data_buf
)
Parameters:

dev_idx         [in]      connected device ID.
from_ddr        [in]      query models in ddr (1) or flash (0)
data_buf        [out]     the pointer to store model info
                          data: total_number(4 bytes) + model_id_1(4 bytes) + model_id_2(4 bytes)

Returns:

0 on succeed, -1 on failure

Notes:

caller must allocate memory for data_buf.


kdp_get_nef_model_metadata

To request for metadata of NEF model file

int kdp_get_nef_model_metadata(
    char* model_data
    uint32_t model_size
    struct kdp_metadata_s* metadata
)
Parameters:

model_data      [in]      nef model data
model_size      [in]      size of NEF model
metadata        [out]     returned metadata

Returns:

0 on succeed, -1 on failure


kdp_get_res_mask

Get result mask with bit flags

uint16_t kdp_get_res_mask(
    bool fd
    bool lm
    bool fr
    bool liveness
    bool score
)
Parameters:

fd              [in]      checked if need face detection output
lm              [in]      checked if need face detection output
fr              [in]      checked if need feature map of a face
liveness        [in]      checked if need liveness detection output (Beta)
score           [in]      checked if need the recognition score output

Returns:

mask of bit flags

Notes:


kdp_get_res_size

Get result size for memory allocation

uint32_t kdp_get_res_size(
    bool fd
    bool lm
    bool fr
    bool liveness
    bool score
)
Parameters:

fd              [in]      checked if need face detection output
lm              [in]      checked if need face detection output
fr              [in]      checked if need feature map of a face
liveness        [in]      checked if need liveness detection output (Beta)
score           [in]      checked if need the recognition score output

Returns:

result size in bytes

Notes:


kdp_hico_retrieve_res

request to get image inference results

int kdp_hico_retrieve_res(
    int dev_idx
    uint32_t img_id
    uint32_t* rsp_code
    uint32_t* r_size
    char* r_data
)
Parameters:

dev_idx         [in]      connected device ID
img_id          [in]      sequence id to get inference results of an image with the specified id
rsp_code        [out]     response code from device
r_size          [out]     inference data size
r_res           [out]     inference result data

Returns:

0 on succeed, error code on failure


kdp_hico_send_image

Send an image

int kdp_hico_send_image(
    int dev_idx
    char* img_buf
    int buf_len
    uint32_t img_id
    uint32_t* rsp_code
)
Parameters:

dev_idx         [in]      connected device ID
img_buf         [in]      the image buffer
buf_len         [in]      the buffer size
img_id          [in]      the sequence id of the image
rsp_code        [out]     response code from device

Returns:

0 on succeed, error code on failure

Notes:

Before calling this API, must call kdp_start_hico_mode() first


kdp_import_db

To import customer DB image to device

int kdp_import_db(
    int dev_idx
    char* p_buf
    uint32_t p_len
)
Parameters:

dev_idx         [in]      connected device ID
buf             [in]      the customer's image buffer pointer
p_len           [in]      image size in buffer

Returns:

0 on succeed, error code on failure

Notes:


kdp_init_log

Init the host lib internal log

int kdp_init_log(
    const char* dir
    const char* name
)
Parameters:

dir             [in]      the directory name of the log file
name            [in]      the log file name

Returns:

0 on succeed, -1 on failure


kdp_isi_config

To configure the model for the supported app id

int kdp_isi_config(
    int dev_idx
    uint32_t model_id
    uint32_t param
    uint32_t *rsp_code
)
Parameters:

dev_idx         [in]      connected device ID
model_id        [in]      model id to run image inference
param           [in]      the parameter needed for the model
rsp_code        [out]     response code from ISI command handler on device

Returns:

0 on succeed, error code on failure


kdp_isi_inference

Start an inference with an image

int kdp_isi_inference(
    int dev_idx
    char* img_buf
    int buf_len
    uint32_t img_id
    uint32_t* rsp_code
    uint32_t* img_buf_available
)
Parameters:

dev_idx         [in]      connected device ID
img_buf         [in]      the image buffer
buf_len         [in]      the buffer size
img_id          [in]      the sequence id of the image
rsp_code        [out]     response code from device
img_buf_available[out]     the number of image buffer still available for input

Returns:

0 on succeed, error code on failure

Notes:

Before calling this API, must call kdp_start_isi() first


kdp_isi_inference_ext

Start an inference with an image and image header

int kdp_isi_inference_ext(
    int dev_idx
    char* img_buf
    struct kdp_isi_image_header_s *img_header
    uint16_t header_len
    uint32_t* rsp_code
    uint32_t* img_buf_available
)
Parameters:

dev_idx         [in]      connected device ID
img_buf         [in]      the image buffer
buf_len         [in]      the buffer size
img_id          [in]      the sequence id of the image
rsp_code        [out]     response code from device
img_buf_available[out]     the number of image buffer still available for input

Returns:

0 on succeed, error code on failure

Notes:

Before calling this API, must call kdp_start_isi() first


kdp_isi_retrieve_data

To request for dump memory

int kdp_isi_retrieve_data(
    int dev_idx
    uint32_t img_id
    uint32_t flags
    uint32_t* rsp_code
    uint32_t* r_size
    char* r_data
)
Parameters:

dev_idx         [in]      connected device ID
img_id          [in]      sequence id / model id
flags:          [in]      0 retrieve results, others  use to dump model's input/output memory
rsp_code        [out]     response code from device
r_size          [out]     inference data size
r_res           [out]     inference result data

Returns:

0 on succeed, error code on failure


kdp_isi_retrieve_res

To request for getting an inference results

int kdp_isi_retrieve_res(
    int dev_idx
    uint32_t img_id
    uint32_t* rsp_code
    uint32_t* r_size
    char* r_data
)
Parameters:

dev_idx         [in]      connected device ID
img_id          [in]      sequence id to get inference results of an image with the specified id
rsp_code        [out]     response code from device
r_size          [out]     inference data size
r_res           [out]     inference result data

Returns:

0 on succeed, error code on failure


kdp_jpeg_dec

start jpeg decoding

int kdp_jpeg_dec(
    int dev_idx
    int img_seq
    uint8_t *in_img_buf
    uint32_t in_img_len
    uint32_t *out_img_buf
    uint32_t *out_img_len
)
Parameters:

dev_idx         [in]      connected device ID
img_seq         [in]      image sequential number
in_img_buf      [in]      input JPEG image buffer
in_img_len      [in]      input image size in bytes
out_img_buf     [out]     returned encoding ouput YUV buffer address in SCPU (not host address)
out_img_len     [out]     returned encoding output valid length,
                          host can use this size to allocate memory to retrieve jpeg data from SCPU

Returns:

0 on succeed, error code on failure

Notes:

For KL720 only


kdp_jpeg_dec_config

Configure for jpeg decoding

int kdp_jpeg_dec_config(
    int dev_idx
    int img_seq
    int width
    int height
    int fmt
    int len
)
Parameters:

dev_idx         [in]      connected device ID
img_seq         [in]      image sequential number
width           [in]      width of the decoded output image
height          [in]      height of the decoded ouput image
fmt             [in]      decoded output YUV image format
len             [in]      input jpeg valid length in bytes

Returns:

0 on succeed, error code on failure

Notes:

for KL720 only


kdp_jpeg_dec_retrieve_res

To retrieve jpeg decoding output

int kdp_jpeg_dec_retrieve_res(
    int dev_idx
    uint32_t img_seq
    uint32_t* rsp_code
    uint32_t* r_size
    char* r_data
)
Parameters:

dev_idx         [in]      connected device ID
img_seq         [in]      image sequential number
rsp_code        [out]     return code
r_size          [out]     returned result size (bytes)
r_data          [out]     returned data buffer (host address)

Returns:

0 on succeed, error code on failure

Notes:

For KL720 only


kdp_jpeg_enc

Start jpeg encoding

int kdp_jpeg_enc(
    int dev_idx
    int img_seq
    uint8_t *in_img_buf
    uint32_t in_img_len
    uint32_t *out_img_buf
    uint32_t *out_img_len
)
Parameters:

dev_idx         [in]      connected device ID
img_seq         [in]      image sequential number
in_img_buf      [in]      input YUV image buffer
in_img_len      [in]      input image size in bytes
out_img_buf     [out]     returned encoding ouput jpeg buffer address in SCPU (not host address)
out_img_len     [out]     returned encoding output valid length, host can use this size to allocate memory to retrieve jpeg data from SCPU

Returns:

0 on succeed, error code on failure

Notes:

for KL720 only


kdp_jpeg_enc_config

To configure for jpeg enc

int kdp_jpeg_enc_config(
    int dev_idx
    int img_seq
    int width
    int height
    int fmt
    int quality
)
Parameters:

dev_idx         [in]      connected device ID
img_seq         [in]      image sequential number
width           [in]      width of the image
height          [in]      height of the image
fmt             [in]      input YUV image format
quality         [in]      jpeg encoding quality 0 ~ 100, normally 70~75 is recommended

Returns:

0 on succeed, error code on failure

Notes:

for KL720 only


kdp_jpeg_enc_retrieve_res

Retrieve jpeg encoding output

int kdp_jpeg_enc_retrieve_res(
    int dev_idx
    uint32_t img_seq
    uint32_t* rsp_code
    uint32_t* r_size
    char* r_data
)
Parameters:

dev_idx         [in]      connected device ID
img_seq         [in]      image sequential number
rsp_code        [out]     return code
r_size          [out]     returned result size (bytes)
r_data          [out]     returned data buffer (host address)

Returns:

0 on succeed, error code on failure

Notes:

for KL720 only


kdp_lib_de_init

Free the resources used by host lib

int kdp_lib_de_init()
Returns:

0 on succeed, -1 on failure


kdp_lib_init

To init the host library

int kdp_lib_init()
Returns:

0 on succeed, -1 on failure


kdp_lib_start

To start the host library to wait for messages

int kdp_lib_start()
Returns:

0 on succeed, -1 on failure


kdp_list_users

To test if user in device DB

int kdp_list_users(
    int dev_idx
    int user_id
)
Parameters:

dev_idx         [in]      connected device ID
user_id         [in]      the user to be listed.(starts from 1)

Returns:

0 on succeed, error code on failure

Notes:


kdp_mp_gpio_set

To set gpio

int kdp_mp_gpio_set(
    int dev_idx
    uint32_t pin
    uint32_t value
)
Parameters:

dev_idx         [in]      connected device ID
pin             [in]      gpio pin index (0~31)
value           [in]      value to set (0 or non-zero)

Returns:

0 on succeed, -1 on failure

Notes:

for KL720 only


kdp_query_fm_by_user

To query user's feature map from device DB

int kdp_query_fm_by_user(
    int dev_idex
    char* fm
    uint32_t user_id
    uint32_t face_id
)
Parameters:

dev_idx         [in]      connected device ID
fm              [out]     the buffer to store queried fm data
user_id         [in]      the user id to be queried. start from 1
face_id         [in]      the fm id to be queried. start from 1

Returns:

0 on succeed, error code on failure

Notes:


kdp_register_user

To register the extracted face features to DB in device Flash

int kdp_register_user(
    int dev_idx
    uint32_t user_id
)
Parameters:

dev_idx         [in]      connected device ID
user_id         [in]      the user id that be registered.

Returns:

0 on succeed, error code on failure

Notes:


kdp_register_user_by_fm

To register user by feature map to device DB

int kdp_register_user_by_fm(
    int dev_idx
    uint32_t user_id
    char* fm
    int fm_len
)
Parameters:

dev_idx         [in]      connected device ID
user_id         [in]      the user to be register. start from 1
fm              [in]      feature map data to register
fm_len          [in]      feature map data size in byte

Returns:

fm index on succeed, -1 on failure

Notes:


kdp_remove_user

To remove user from device DB

int kdp_remove_user(
    int dev_idx
    uint32_t user_id
)
Parameters:

dev_idx         [in]      connected device ID
user_id         [in]      the user to be removed. 0 for all users

Returns:

0 on succeed, error code on failure

Notes:


kdp_report_sys_status

To request for system status

int kdp_report_sys_status(
    int dev_idx
    uint32_t* sfw_id
    uint32_t* sbuild_id
    uint16_t* sys_status
    uint16_t* app_status
    uint32_t* nfw_id
    uint32_t* nbuild_id
)
Parameters:

dev_idx         [in]      connected device ID. A host can connect several devices
sfw_id          [out]     the version of the scpu firmware
sbuild_id       [out]     the build number of the scpu firmware
sys_status      [out]     system status (Beta)
app_status      [out]     application status (Beta)
nfw_id          [out]     the version of the ncpu firmware (reserved)
nbuild_id       [out]     the build number of the ncpu firmware (reserved)

Returns:

0 on succeed, -1 on failure


kdp_reset_sys

To request for doing system reset

int kdp_reset_sys(
    int dev_idx
    uint32_t reset_mode
)
Parameters:

dev_idx         [in]      connected device ID. A host can connect several devices
reset_mode      [in]      specifies the reset mode
                          0 - no operation
                          1 - reset message protocol
                          3 - switch to suspend mode
                          4 - switch to active mode
                          255 - reset whole system
                          256 - system shutdown(RTC)
                          0x1000xxxx - reset debug output level

Returns:

0 on succeed, error code on failure


kdp_scan_usb_devices

To scan all Kneron devices and report a list

int kdp_scan_usb_devices(
    kdp_device_info_list_t **list
)
Parameters:

list            [in]      an input, the API will allocate memory and fullfill the content.

Returns:

always 0


kdp_set_ckey

To set a customized key

int kdp_set_ckey(
    int dev_idx
    uint32_t ckey
    uint32_t *set_status
)
Parameters:

dev_idx         [in]      connected device ID
ckey            [in]      the key to program
set_status      [out]     status code
                          0xFFFF: command not supported in this FW
                          0x0   : OK
                          0x1   : cannot burn eFuse
                          0x2   : eFuse protected

Returns:

0 on succeed, -1 on failure

Notes:

WARNING!!! This API is only for ODM/OEM company


kdp_set_db_config

Configurate DB structure

int kdp_set_db_config(
    int dev_idx
    kdp_db_config_t* db_config
)
Parameters:

dev_idx         [in]      connected device ID
db_config       [in]      configuration data

Returns:

0 on succeed, error code on failure

Notes:


kdp_set_db_version

Set DB version number

int kdp_set_db_version(
    int dev_idx
    uint32_t db_version
)
Parameters:

dev_idx         [in]      connected device ID
db_version      [in]      version number of DB

Returns:

0 on succeed, error code on failure

Notes:


kdp_set_sbt_key

To set security boot key

int kdp_set_sbt_key(
    int dev_idx
    uint32_t entry
    uint32_t key
    uint32_t *set_status
)
Parameters:

dev_idx         [in]      connected device ID
entry           [in]      0~13, security key offset
key             [in]      key value
set_status      [out]     status code

Returns:

0 on succeed, -1 on failure

Notes:

for KL720 only


kdp_sfid_set_float_value

Set sfid float configuration value by value type

int kdp_sfid_set_float_value(
    int dev_idx
    uint32_t value_type
    float value
)
Parameters:

dev_idx         [in]      connected device ID.
value_type      [in]      the required configuration value type.
                          SFID_FR_UNMASKED_THRESHOLD   : threshold used to match unmasked face recognition result.
                          - range: 0.0 < threshold < 1.0
                          - threshold == 0.0: use default threshold
                          SFID_FR_MASKED_THRESHOLD     : threshold used to match masked face recognition result
                          - range: 0.0 < threshold < 1.0
                          - threshold == 0.0: use default threshold
value           [in]      float configuration value

Returns:

0 on succeed, error code on failure

Notes:


kdp_start_dme

To request for starting dynamic model execution (Deprecated)

int kdp_start_dme(
    int dev_idx
    uint32_t model_size
    char* data
    int dat_size
    uint32_t* ret_size
    char* img_buf
    int buf_len
)
Parameters:

dev_idx         [in]      connected device ID
model_size      [in]      size of inference model
data            [in]      firmware setup data
dat_size        [in]      setup data size
ret_size        [out]     returned model size
img_buf         [in]      the model file buffer
buf_len         [in]      the buffer size

Returns:

0 on succeed, error code on failure


kdp_start_dme_ext

To request for starting dynamic model execution

int kdp_start_dme_ext(
    int dev_idx
    char* nef_model_data
    uint32_t model_size
    uint32_t* ret_size
)
Parameters:

dev_idx         [in]      connected device ID
model_data      [in]      NEF model data
model_size      [in]      size of nef model
ret_size        [out]     returned model size

Returns:

0 on succeed, error code on failure

Notes:

Only support NEF model file with 1 model Composed model set is not supported


kdp_start_hico_mode

start HICO (Host/camera IN Companion OUT) mode with configuration

int kdp_start_hico_mode(
    int dev_idx
    char* hico_cfg
    int cfg_size
    uint32_t* rsp_code
    uint32_t* buf_size
)
Parameters:

dev_idx         [in]      connected device ID
hico_cfg        [in]      HICO configuration data
cfg_size        [in]      HICO configuration data size
rsp_code        [out]     response code from device
buf_size        [out]     the max buffer size for response and data returned.

Returns:

0 on succeed, error code on failure


kdp_start_isi_mode

start the user isi mode with specified app id and return data size

int kdp_start_isi_mode(
    int dev_idx
    uint32_t app_id
    uint32_t return_size
    uint16_t width
    uint16_t height
    uint32_t format
    uint32_t* rsp_code
    uint32_t* buf_size
)
Parameters:

dev_idx         [in]      connected device ID
app_id          [in]      application id. Refer to common/include/kapp_id.h
return_size     [in]      this size reserved for ISI result
img_width       [in]      the width of input image
img_height      [in]      the height of input image
format          [in]      the input image format
rep_code        [out]     response code
buf_size        [out]     the depth of the image buffer will be returned.

Returns:

0 on succeed, error code on failure

Notes:

For format, refer to common/include/inp.h and find IMAGE_FORMAT_XXX


kdp_start_isi_mode_ext

start the user isi mode with isi configuration

int kdp_start_isi_mode_ext(
    int dev_idx
    char* isi_cfg
    int cfg_size
    uint32_t* rsp_code
    uint32_t* buf_size
)
Parameters:

dev_idx         [in]      connected device ID
isi_cfg         [in]      isi configuration data
cfg_size        [in]      isi configuration data size
rsp_code        [out]     response code from device
buf_size        [out]     the depth of the image buffer will be returned.

Returns:

0 on succeed, error code on failure


kdp_start_isi_mode_ext2

start the user isi mode & configuration for ISI START command

int kdp_start_isi_mode_ext2(
    int dev_idx
    char* isi_cfg
    int cfg_size
    char* nef_model_data
    int model_size
    uint32_t* rsp_code
    uint32_t* buf_size
)
Parameters:

dev_idx         [in]      connected device ID
isi_cfg         [in]      isi configuration data
cfg_size        [in]      isi configuration data size
nef_model_data  [in]      isi model configuration data
model_size      [in]      model data size
rsp_code        [out]     response code from device
buf_size        [out]     the depth of the image buffer will be returned.

Returns:

0 on succeed, error code on failure


kdp_start_reg_user_mode

Start the user register mode

int kdp_start_reg_user_mode(
    int dev_idx
    uint16_t usr_id
    uint16_t img_idx
)
Parameters:

dev_idx         [in]      connected device ID
user_id         [in]      the user id to be registered
img_idx         [in]      the image idx to be saved

Returns:

0 on succeed, -1 on failure

Notes:


kdp_start_sfid_mode

Start the user sfid mode with specified threshold, image format

int kdp_start_sfid_mode(
    int dev_idx
    uint32_t* img_size
    float thresh
    uint16_t width
    uint16_t height
    uint32_t format
)
Parameters:

dev_idx         [in]      connected device ID.
img_size        [in]      the required image file size will be returned for confirmation
thresh          [in]      threshold used to match face recognition result. range: thresh < 1.0
                          thresh == 0: use default threshold
                          thresh <  0: ignore setup threshold
img_width       [in]      the width of input image
img_height      [in]      the height of input image
format          [in]      the input image format

Returns:

0 on succeed, error code on failure

Notes:


kdp_switch_db_index

Switch current DB index

int kdp_switch_db_index(
    int dev_idx
    uint32_t db_idx
)
Parameters:

dev_idx         [in]      connected device ID
db_idx          [in]      index of target db

Returns:

0 on succeed, error code on failure

Notes:


kdp_update_fw

To request for update firmware

int kdp_update_fw(
    int dev_idx
    uint32_t* module_id
    char* img_buf
    int buf_len
)
Parameters:

dev_idx         [in]      connected device ID
module_id       [in]      the module id of which the firmware to be updated
                          0 - no operation
                          1 - scpu module
                          2 - ncpu module
img_buf         [in]      FW image buffer
buf_len         [in]      buffer size

Returns:

0 if succeed, error code for failure


kdp_update_model

To request for update model (Deprecated)

int kdp_update_model(
    int dev_idx
    uint32_t* model_id
    uint32_t model_size
    char* img_buf
    int buf_len
)
Parameters:

dev_idx         [in]      connected device ID
model_id        [in]      (reserved, no function) the model id to be updated
model_size      [in]      the size of the model
img_buf         [in]      the fw image buffer
buf_len         [in]      the buffer size

Returns:

0 if succeed, error code for failure


kdp_update_nef_model

To request for update nef model

int kdp_update_nef_model(
    int dev_idx
    char* img_buf
    int buf_len
)
Parameters:

dev_idx         [in]      connected device ID
img_buf         [in]      the nef model buffer
buf_len         [in]      the buffer size

Returns:

0 if succeed, else error code


kdp_update_spl

To request for update spl

int kdp_update_spl(
    int dev_idx
    uint32_t mode
    uint16_t auth_type
    uint16_t spl_size
    uint8_t* auth_key
    char* spl_buf
    uint32_t* rsp_code
    uint32_t* spl_id
    uint32_t* spl_build
)
Parameters:

dev_idx         [in]      connected device ID
mode            [in]      the command mode to be exercised
auth_type       [in]      the authenticator type
spl_size        [in]      the spl fw image file size
auth_key        [in]      the authenticator key
spl_buf         [in]      the spl fw image buf
rsp_code        [out]     respone code
spl_id          [out]     the id of the spl firmware in device (post command execution)
spl_build       [out]     the build number of the spl firmware

Returns:

0 if succeed, error code for failure

Notes:

WARNING!!! This API is only for ODM/OEM company


kdp_verify_user_id_generic

Perform the face recognition by input image with specified output

int kdp_verify_user_id_generic(
    int dev_idx
    uint16_t* user_id
    char* img_buf
    int buf_len
    uint16_t* mask
    char* res
)
Parameters:

dev_idx         [in]      connected device ID.
user_id         [in]      found matched user ID
img_buf         [in]      the image buffer
buf_len         [in]      the buffer size
mask            [in,out]  input:indicate the mask of requested data, output:responsed flags
res             [out]     pre-allocated memory for the specified output
                          call kdp_get_res_size() to get result size

Returns:

0 on succeed, error code on failure

Notes: