463 lines
17 KiB
C
463 lines
17 KiB
C
/**
|
|
* @file kp_struct.h
|
|
* @brief Kneron PLUS data structure
|
|
* @version 0.1
|
|
* @date 2021-03-22
|
|
*
|
|
* @copyright Copyright (c) 2021 Kneron Inc. All rights reserved.
|
|
*/
|
|
|
|
#pragma once
|
|
|
|
#include <stdint.h>
|
|
#include <stdbool.h>
|
|
|
|
#define APP_PADDING_BYTES 20 /**< Default padding size */
|
|
|
|
#define KDP2_MAGIC_TYPE_COMMAND 0xAB67CD13 /**< Magic number for data check */
|
|
#define KDP2_MAGIC_TYPE_INFERENCE 0x11FF22AA /**< Magic number for data check */
|
|
#define KDP2_MAGIC_TYPE_CUSTOMIZED 0x11FF33CC /**< Magic number for customized data */
|
|
|
|
/**
|
|
* @brief return code of most APIs.
|
|
*/
|
|
enum KP_API_RETURN_CODE
|
|
{
|
|
KP_SUCCESS = 0,
|
|
|
|
/* libusb error code */
|
|
KP_ERROR_USB_IO_N1 = -1,
|
|
KP_ERROR_USB_INVALID_PARAM_N2 = -2,
|
|
KP_ERROR_USB_ACCESS_N3 = -3,
|
|
KP_ERROR_USB_NO_DEVICE_N4 = -4,
|
|
KP_ERROR_USB_NOT_FOUND_N5 = -5,
|
|
KP_ERROR_USB_BUSY_N6 = -6,
|
|
KP_ERROR_USB_TIMEOUT_N7 = -7,
|
|
KP_ERROR_USB_OVERFLOW_N8 = -8,
|
|
KP_ERROR_USB_PIPE_N9 = -9,
|
|
KP_ERROR_USB_INTERRUPTED_N10 = -10,
|
|
KP_ERROR_USB_NO_MEM_N11 = -11,
|
|
KP_ERROR_USB_NOT_SUPPORTED_N12 = -12,
|
|
KP_ERROR_USB_OTHER_N99 = -99,
|
|
|
|
/* host error code */
|
|
KP_ERROR_MEMORY_ALLOCATION_FAILURE_9 = 9,
|
|
KP_ERROR_DEVICE_NOT_EXIST_10 = 10,
|
|
KP_ERROR_DEVICE_INCORRECT_RESPONSE_11 = 11,
|
|
KP_ERROR_INVALID_PARAM_12 = 12,
|
|
KP_ERROR_SEND_DESC_FAIL_13 = 13,
|
|
KP_ERROR_SEND_DATA_FAIL_14 = 14,
|
|
KP_ERROR_SEND_DATA_TOO_LARGE_15 = 15,
|
|
KP_ERROR_RECV_DESC_FAIL_16 = 16,
|
|
KP_ERROR_RECV_DATA_FAIL_17 = 17,
|
|
KP_ERROR_RECV_DATA_TOO_LARGE_18 = 18,
|
|
KP_ERROR_FW_UPDATE_FAILED_19 = 19,
|
|
KP_ERROR_FILE_OPEN_FAILED_20 = 20,
|
|
KP_ERROR_INVALID_MODEL_21 = 21,
|
|
KP_ERROR_IMAGE_RESOLUTION_TOO_SMALL_22 = 22,
|
|
KP_ERROR_IMAGE_INVALID_WIDTH_23 = 23,
|
|
KP_ERROR_INVALID_FIRMWARE_24 = 24,
|
|
KP_ERROR_RESET_FAILED_25 = 25,
|
|
KP_ERROR_DEVICES_NUMBER_26 = 26,
|
|
KP_ERROR_CONFIGURE_DEVICE_27 = 27,
|
|
KP_ERROR_CONNECT_FAILED_28 = 28,
|
|
KP_ERROR_DEVICE_GROUP_MIX_PRODUCT_29 = 29,
|
|
KP_ERROR_RECEIVE_INCORRECT_HEADER_STAMP_30 = 30,
|
|
KP_ERROR_RECEIVE_SIZE_MISMATCH_31 = 31,
|
|
KP_ERROR_RECEIVE_JOB_ID_MISMATCH_32 = 32,
|
|
KP_ERROR_INVALID_CUSTOMIZED_JOB_ID_33 = 33,
|
|
KP_ERROR_FW_LOAD_FAILED_34 = 34,
|
|
KP_ERROR_MODEL_NOT_LOADED_35 = 35,
|
|
|
|
KP_ERROR_OTHER_99 = 99,
|
|
|
|
/* firmware error code */
|
|
KP_FW_ERROR_UNKNOWN_APP = 100,
|
|
KP_FW_INFERENCE_ERROR_101 = 101,
|
|
KP_FW_DDR_MALLOC_FAILED_102 = 102,
|
|
KP_FW_INFERENCE_TIMEOUT_103 = 103,
|
|
KP_FW_LOAD_MODEL_FAILED_104 = 104,
|
|
KP_FW_CONFIG_POST_PROC_ERROR_MALLOC_FAILED_105 = 105,
|
|
KP_FW_CONFIG_POST_PROC_ERROR_NO_SPACE_106 = 106,
|
|
KP_FW_IMAGE_SIZE_NOT_MATCH_MODEL_INPUT_107 = 107,
|
|
KP_FW_NOT_SUPPORT_PREPROCESSING_108 = 108,
|
|
|
|
/* ncpu error code (sync with ipc.h) */
|
|
KP_FW_NCPU_ERR_BEGIN = 200,
|
|
KP_FW_NCPU_INVALID_IMAGE_201 = 201,
|
|
|
|
/* firmware eFuse error code */
|
|
KP_FW_EFUSE_CAN_NOT_BURN = 300,
|
|
KP_FW_EFUSE_PROTECTED = 301,
|
|
KP_FW_EFUSE_OTHER = 302,
|
|
};
|
|
|
|
/**
|
|
* @brief enum for USB speed mode
|
|
*/
|
|
typedef enum
|
|
{
|
|
KP_USB_SPEED_UNKNOWN = 0,
|
|
KP_USB_SPEED_LOW = 1,
|
|
KP_USB_SPEED_FULL = 2,
|
|
KP_USB_SPEED_HIGH = 3,
|
|
KP_USB_SPEED_SUPER = 4,
|
|
} kp_usb_speed_t;
|
|
|
|
/**
|
|
* @brief enum for USB PID(Product ID)
|
|
*/
|
|
typedef enum
|
|
{
|
|
KP_DEVICE_KL520 = 0x100, /**< KL520 USB PID */
|
|
KP_DEVICE_KL720 = 0x720, /**< KL720 USB PID */
|
|
} kp_product_id_t;
|
|
|
|
/**
|
|
* @brief reset mode
|
|
*/
|
|
typedef enum
|
|
{
|
|
KP_RESET_REBOOT = 0, /**< Higheset level to reset Kneron device. Kneron device would disconnect after this reset. */
|
|
KP_RESET_INFERENCE = 1, /**< Soft reset: reset inference FIFO queue. */
|
|
KP_RESET_SHUTDOWN = 2, /**< Shut down Kneron device. For KL520, only useful if HW circuit supports (ex. 96 bord), dongle is not supported. For KL720, this function is not supported. */
|
|
} kp_reset_mode_t;
|
|
|
|
/**
|
|
* @brief enum for generic raw data channel ordering
|
|
*/
|
|
typedef enum
|
|
{
|
|
KP_CHANNEL_ORDERING_HCW = 0, /**< KL520 default, height/channel/width in order */
|
|
KP_CHANNEL_ORDERING_CHW = 1, /**< KL720 default, channel/height/width in order */
|
|
} kp_channel_ordering_t;
|
|
|
|
/**
|
|
* @brief information of device (USB)
|
|
*/
|
|
typedef struct
|
|
{
|
|
uint32_t port_id; /**< an unique ID representing for a Kneron device, can be used as input while connecting devices */
|
|
uint16_t vendor_id; /**< supposed to be 0x3231. */
|
|
uint16_t product_id; /**< enum kp_product_id_t. */
|
|
int link_speed; /**< enum kp_usb_speed_t. */
|
|
uint32_t kn_number; /**< KN number. */
|
|
bool isConnectable; /**< indicate if this device is connectable. */
|
|
char port_path[20]; /**< "busNo-hub_portNo-device_portNo"
|
|
ex: "1-2-3", means bus 1 - (hub) port 2 - (device) port 3 */
|
|
char firmware[30]; /**< Firmware description. */
|
|
} __attribute__((aligned(4))) kp_device_descriptor_t;
|
|
|
|
/**
|
|
* @brief information of connected devices from USB perspectives.
|
|
*/
|
|
typedef struct
|
|
{
|
|
int num_dev; /**< connected devices */
|
|
kp_device_descriptor_t device[]; /**< real index range from 0 ~ (num_dev-1) */
|
|
} __attribute__((aligned(4))) kp_devices_list_t;
|
|
|
|
/**
|
|
* @brief image format supported for inference.
|
|
*/
|
|
typedef enum
|
|
{
|
|
KP_IMAGE_FORMAT_UNKNOWN = 0x0,
|
|
KP_IMAGE_FORMAT_RGB565 = 0x1, /**< RGB565 16bits */
|
|
KP_IMAGE_FORMAT_RGBA8888 = 0x2, /**< RGBA8888 32bits */
|
|
KP_IMAGE_FORMAT_YUYV = 0x3, /**< YUYV 16bits */
|
|
KP_IMAGE_FORMAT_RAW8 = 0x4, /**< RAW 8bits */
|
|
} kp_image_format_t;
|
|
|
|
/**
|
|
* @brief a basic descriptor for a model
|
|
*/
|
|
typedef struct
|
|
{
|
|
uint32_t id; /**< model ID */
|
|
uint32_t max_raw_out_size; /**< needed raw output buffer size for this model */
|
|
uint32_t width; /**< the input width of this model */
|
|
uint32_t height; /**< the input height of this model */
|
|
uint32_t channel; /**< the input channel of this model */
|
|
kp_image_format_t img_format; /**< the input image format of this model */
|
|
} __attribute__((aligned(4))) kp_single_model_descriptor_t;
|
|
|
|
/**
|
|
* @brief a basic descriptor for a NEF
|
|
*/
|
|
typedef struct
|
|
{
|
|
uint32_t crc; /**< crc of all models */
|
|
int num_models; /**< number of models */
|
|
kp_single_model_descriptor_t models[10]; /**< model descriptors */
|
|
} __attribute__((aligned(4))) kp_model_nef_descriptor_t;
|
|
|
|
/**
|
|
* @brief a handle represent connected Kneron device.
|
|
*/
|
|
typedef struct
|
|
{
|
|
int timeout; /**< global timeout value for all USB communications with the device */
|
|
int num_device; /**< number of devices in device group */
|
|
kp_product_id_t product_id; /**< enum kp_product_id_t */
|
|
kp_model_nef_descriptor_t loaded_model_desc; /**< a basic descriptor for a NEF */
|
|
} __attribute__((aligned(4))) kp_device_group_s;
|
|
|
|
/**
|
|
* @brief a pointer handle represent connected Kneron device.
|
|
*/
|
|
typedef kp_device_group_s *kp_device_group_t;
|
|
|
|
/**
|
|
* @brief normalization mode
|
|
*/
|
|
typedef enum
|
|
{
|
|
KP_NORMALIZE_DISABLE = 0xFF, /**< disable normalize */
|
|
KP_NORMALIZE_KNERON = 0x1, /**< RGB/256 - 0.5, refer to the toolchain manual */
|
|
KP_NORMALIZE_TENSOR_FLOW = 0x2, /**< RGB/127.5 - 1.0, refer to the toolchain manual */
|
|
KP_NORMALIZE_YOLO = 0x3, /**< RGB/255.0, refer to the toolchain manual */
|
|
KP_NORMALIZE_CUSTOMIZED_DEFAULT = 0x4, /**< customized, default, refer to the toolchain manual */
|
|
KP_NORMALIZE_CUSTOMIZED_SUB128 = 0x5, /**< customized, subtract 128, refer to the toolchain manual */
|
|
KP_NORMALIZE_CUSTOMIZED_DIV2 = 0x6, /**< customized, divide by 2, refer to the toolchain manual */
|
|
KP_NORMALIZE_CUSTOMIZED_SUB128_DIV2 = 0x7, /**< customized, subtract 128 and divide by 2, refer to the toolchain manual */
|
|
} kp_normalize_mode_t;
|
|
|
|
/**
|
|
* @brief resize mode
|
|
*/
|
|
typedef enum
|
|
{
|
|
KP_RESIZE_DISABLE = 0x1, /**< Disable Resize in Pre-process */
|
|
KP_RESIZE_ENABLE = 0x2, /**< Enable Resize in Pre-process */
|
|
} kp_resize_mode_t;
|
|
|
|
/**
|
|
* @brief padding mode
|
|
*/
|
|
typedef enum
|
|
{
|
|
KP_PADDING_DISABLE = 0x1, /**< Disable Padding in Pre-process */
|
|
KP_PADDING_CORNER = 0x2, /**< Using Corner Padding in Pre-process */
|
|
KP_PADDING_SYMMETRIC = 0x3, /**< Using Symmetric Padding in Pre-process */
|
|
} kp_padding_mode_t;
|
|
|
|
/**
|
|
* @brief data structure for inference configurations
|
|
*/
|
|
typedef struct
|
|
{
|
|
bool enable_frame_drop; /**< enable this to keep inference non-blocking by dropping oldest and unprocessed frames */
|
|
} __attribute__((aligned(4))) kp_inf_configuration_t;
|
|
|
|
/**
|
|
* @brief data structure for a crop
|
|
*/
|
|
typedef struct
|
|
{
|
|
uint32_t crop_number; /**< index number */
|
|
|
|
uint32_t x1; /**< top-left corner: x */
|
|
uint32_t y1; /**< top-left corner: y */
|
|
uint32_t width; /**< width */
|
|
uint32_t height; /**< height */
|
|
} __attribute__((aligned(4))) kp_inf_crop_box_t;
|
|
|
|
#define MAX_CROP_BOX 4 /**< MAX crop count */
|
|
|
|
/**
|
|
* @brief inference descriptor for images
|
|
*/
|
|
typedef struct
|
|
{
|
|
uint32_t inference_number; /**< inference sequence number */
|
|
uint32_t width; /**< image width */
|
|
uint32_t height; /**< image height */
|
|
uint32_t resize_mode; /**< resize mode, refer to kp_resize_mode_t */
|
|
uint32_t padding_mode; /**< padding mode, refer to kp_resize_mode_t */
|
|
uint32_t image_format; /**< image format, refer to kp_image_format_t */
|
|
uint32_t normalize_mode; /**< inference normalization, refer to kp_normalize_mode_t */
|
|
uint32_t model_id; /**< target inference model ID */
|
|
uint32_t crop_count; /**< crop count */
|
|
kp_inf_crop_box_t inf_crop[MAX_CROP_BOX]; /**< box information to crop */
|
|
|
|
} __attribute__((aligned(4))) kp_generic_raw_image_header_t;
|
|
|
|
/**
|
|
* @brief inference RAW output descriptor
|
|
*/
|
|
typedef struct
|
|
{
|
|
uint32_t inference_number; /**< inference sequence number */
|
|
uint32_t crop_number; /**< crop box sequence number */
|
|
uint32_t num_output_node; /**< total number of output nodes */
|
|
} __attribute__((aligned(4))) kp_generic_raw_result_header_t;
|
|
|
|
/**
|
|
* @brief inference descriptor for images bypass pre-processing
|
|
*/
|
|
typedef struct
|
|
{
|
|
uint32_t inference_number; /**< inference sequence number */
|
|
uint32_t image_buffer_size; /**< image buffer size */
|
|
uint32_t model_id; /**< target inference model ID */
|
|
} __attribute__((aligned(4))) kp_generic_raw_bypass_pre_proc_image_header_t;
|
|
|
|
/**
|
|
* @brief inference RAW output descriptor for bypass pre-processing
|
|
*/
|
|
typedef struct
|
|
{
|
|
uint32_t inference_number; /**< inference sequence number */
|
|
uint32_t crop_number; /**< crop box sequence number */
|
|
uint32_t num_output_node; /**< total number of output nodes */
|
|
} __attribute__((aligned(4))) kp_generic_raw_bypass_pre_proc_result_header_t;
|
|
|
|
/**
|
|
* @brief Metadata of RAW node output in fixed-point format
|
|
*/
|
|
typedef struct
|
|
{
|
|
uint32_t height; /**< node height */
|
|
uint32_t channel; /**< node channel */
|
|
uint32_t width; /**< node width, should be aligned to 16 bytes for futher processing due to low level output */
|
|
int32_t radix; /**< radix for fixed/floating point conversion */
|
|
float scale; /**< scale for fixed/floating point conversion */
|
|
} __attribute__((aligned(4))) kp_inf_raw_fixed_node_metadata_t;
|
|
|
|
/**
|
|
* @brief RAW node output in raw fixed-point format (with width padding and device channel ordering)
|
|
*/
|
|
typedef struct
|
|
{
|
|
kp_inf_raw_fixed_node_metadata_t metadata; /**< metadata of RAW node output in fixed-point format */
|
|
uint32_t num_data; /**< total number of fixed-poiont values, should be
|
|
metadata->width (aligned to 16 bytes) * metadata->height * metadata->channel */
|
|
int8_t *data; /**< array of fixed-point values*/
|
|
} __attribute__((aligned(4))) kp_inf_raw_fixed_node_output_t;
|
|
|
|
/**
|
|
* @brief RAW node output in fixed-point format
|
|
*/
|
|
typedef struct
|
|
{
|
|
uint32_t width; /**< node width */
|
|
uint32_t height; /**< node height */
|
|
uint32_t channel; /**< node channel */
|
|
int32_t radix; /**< radix for fixed/floating point conversion */
|
|
float scale; /**< scale for fixed/floating point conversion */
|
|
float factor; /**< conversion factor for fixed-point to floating-point conversion - formula: 1 / (scale * (2 ^ radix)) */
|
|
uint32_t num_data; /**< total number of fixed-point values */
|
|
int8_t data[]; /**< array of fixed-point values */
|
|
} __attribute__((aligned(4))) kp_inf_fixed_node_output_t;
|
|
|
|
/**
|
|
* @brief RAW node output in floating-point format
|
|
*/
|
|
typedef struct
|
|
{
|
|
uint32_t width; /**< node width */
|
|
uint32_t height; /**< node height */
|
|
uint32_t channel; /**< node channel */
|
|
uint32_t num_data; /**< total number of floating-point values */
|
|
float data[]; /**< array of floating-point values */
|
|
} __attribute__((aligned(4))) kp_inf_float_node_output_t;
|
|
|
|
/**
|
|
* @brief describe a bounding box
|
|
*/
|
|
typedef struct
|
|
{
|
|
float x1; /**< top-left corner: x */
|
|
float y1; /**< top-left corner: y */
|
|
float x2; /**< bottom-right corner: x */
|
|
float y2; /**< bottom-right corner: y */
|
|
float score; /**< probability score */
|
|
int32_t class_num; /**< class # (of many) with highest probability */
|
|
} __attribute__((aligned(4))) kp_bounding_box_t;
|
|
|
|
#define YOLO_GOOD_BOX_MAX 100 /**< maximum number of bounding boxes for Yolo models */
|
|
|
|
/**
|
|
* @brief describe a yolo output result after post-processing
|
|
*/
|
|
typedef struct
|
|
{
|
|
uint32_t class_count; /**< total class count detectable by model */
|
|
uint32_t box_count; /**< boxes of all classes */
|
|
kp_bounding_box_t boxes[YOLO_GOOD_BOX_MAX]; /**< box information */
|
|
} __attribute__((aligned(4))) kp_yolo_result_t;
|
|
|
|
#define LAND_MARK_POINTS 5 /**< the number of land marks points */
|
|
|
|
/**
|
|
* @brief decribe a point
|
|
*/
|
|
typedef struct
|
|
{
|
|
uint32_t x; /**< x value */
|
|
uint32_t y; /**< y value */
|
|
} __attribute__((aligned(4))) kp_point_t;
|
|
|
|
/**
|
|
* @brief describe a landmark
|
|
*/
|
|
typedef struct
|
|
{
|
|
kp_point_t marks[LAND_MARK_POINTS]; /**< landmark points */
|
|
float score; /**< score of this landmark */
|
|
float blur; /**< blur score of this landmark */
|
|
int32_t class_num; /**< class number */
|
|
} __attribute__((aligned(4))) kp_landmark_result_t;
|
|
|
|
#define FR_FEAT_LENGTH 256 /**< the length of one feature map */
|
|
|
|
/**
|
|
* @brief describe a feature map
|
|
*/
|
|
typedef struct {
|
|
float feature_map[FR_FEAT_LENGTH]; /**< feature map in floating point */
|
|
int8_t feature_map_fixed[FR_FEAT_LENGTH]; /**< feature map in fixed point */
|
|
} __attribute__((aligned(4))) kp_fr_result_t;
|
|
|
|
/**
|
|
* @brief describe a classification result
|
|
*/
|
|
typedef struct
|
|
{
|
|
int32_t class_num; /**< class # (of many) with highest probability */
|
|
float score; /**< probability score */
|
|
} __attribute__((aligned(4))) kp_classification_result_t;
|
|
|
|
/**
|
|
* @brief describe version string
|
|
*/
|
|
typedef struct
|
|
{
|
|
uint8_t reserved; /**< for backward compatibility */
|
|
uint8_t major; /**< major number */
|
|
uint8_t minor; /**< minor number */
|
|
uint8_t update; /**< update number */
|
|
uint32_t build; /**< build number */
|
|
} __attribute__((aligned(4))) kp_firmware_version_t;
|
|
|
|
/**
|
|
* @brief describe system information
|
|
*/
|
|
typedef struct
|
|
{
|
|
uint32_t kn_number; /**< Chip K/N number */
|
|
kp_firmware_version_t firmware_version; /**< FW version */
|
|
} __attribute__((aligned(4))) kp_system_info_t;
|
|
|
|
/**
|
|
* @brief header stamp for user-defined data transfer
|
|
*/
|
|
typedef struct
|
|
{
|
|
uint32_t magic_type; /**< must be 'KDP2_MAGIC_TYPE_INFERENCE' */
|
|
uint32_t total_size; /**< total size of user-defined header data struct and data (image) */
|
|
uint32_t job_id; /**< user-defind ID to synchronize with firmware side, must >= 1000 */
|
|
uint32_t status_code; /**< this field is valid only for result data, refer to KP_API_RETURN_CODE */
|
|
} __attribute__((aligned(4))) kp_inference_header_stamp_t;
|