K230 DPU API参考
1. 概述
1.1 概述
DPU 主要负责 3D 结构光的深度计算，为 3D 人脸识别提供深度信息。
1.2 功能描述
1.2.1 绑定模式调用流程
1.2.2 非绑定模式调用流程
2. API 参考
2.1 DPU 使用
该功能模块提供以下API：
- kd_mpi_dpu_init
- kd_mpi_dpu_delete
- kd_mpi_dpu_parse_file
- kd_mpi_dpu_set_dev_attr
- kd_mpi_dpu_get_dev_attr
- kd_mpi_dpu_set_ref_image
- kd_mpi_dpu_set_processed_ref_image
- kd_mpi_dpu_set_template_image
- kd_mpi_dpu_start_dev
- kd_mpi_dpu_set_chn_attr
- kd_mpi_dpu_get_chn_attr
- kd_mpi_dpu_start_chn
- kd_mpi_dpu_stop_chn
- kd_mpi_dpu_send_frame
- kd_mpi_dpu_get_frame
- kd_mpi_dpu_release_frame
2.1.1 kd_mpi_dpu_init
【描述】
初始化 dpu 设备
【语法】
k_s32 kd_mpi_dpu_init(k_dpu_init_t *init);
【参数】
| 参数名称 | 描述 | 输入/输出 |
|---|---|---|
| init | 初始化 dpu 设备的结构体指针。 | 输入 |
【返回值】
| 返回值 | 描述 |
|---|---|
| 0 | 成功 |
| 非0 | 失败，其值参见错误码 |
【芯片差异】
无。
【需求】
- 头文件：mpi_dpu_api.h
- 库文件：libdpu.a
【注意】
无
【举例】
无
【相关主题】
2.1.2 kd_mpi_dpu_delete
【描述】
删除已经初始化的 dpu 设备。
【语法】
k_s32 kd_mpi_dpu_delete();
【参数】
| 参数名称 | 描述 | 输入/输出 |
|---|---|---|
| 无 | 无 | 无 |
【返回值】
| 返回值 | 描述 |
|---|---|
| 0 | 成功 |
| 非0 | 失败，其值参见错误码 |
【芯片差异】
无
【需求】
- 头文件：mpi_dpu_api.h
- 库文件：libdpu.a
【注意】
需要在对 dpu 设备初始化以后才可以调用此函数 delete dpu。
【举例】
无
【相关主题】
无
2.1.3 kd_mpi_dpu_parse_file
【描述】
从 dpu 配置文件中解析 dpu 配置参数。
【语法】
k_s32 kd_mpi_dpu_parse_file(const k_char *param_path, k_dpu_dev_param_t *param, k_dpu_lcn_param_t *lcn_param, k_dpu_ir_param_t *ir_param, k_dpu_user_space_t *g_temp_space);
【参数】
| 参数名称 | 描述 | 输入/输出 |
|---|---|---|
| param_path | 配置文件的路径 | 输入 |
| param | dpu 设备参数的结构体指针，从配置文件中解析出来的设备参数保存在此结构体中 | 输出 |
| lcn_param | lcn 通道参数的结构体指针，从配置文件中解析出来的通道参数保存在此结构体中。 | 输出 |
| ir_param | ir 通道参数的结构体指针，从配置文件中解析出来的通道参数保存在此结构体中。 | 输出 |
| g_temp_space | 模板图结构体指针，从配置文件中解析出来的模板图首地址保存在此结构体中。 | 输出 |
【返回值】
| 返回值 | 描述 |
|---|---|
| 0 | 成功 |
| 非0 | 失败，其值参见错误码 |
【芯片差异】
无
【需求】
- 头文件：mpi_dpu_api.h
- 库文件：libdpu.a
【注意】
- dpu 设备参数包括长周期参数和短周期参数。
- lcn_param 和 ir_param 这两个通道参数是 dpu 设备参数的子集，如果已经配置了 dpu 设备参数，可以忽略这两个通道参数。如果需要更改这两个通道参数结构体中的参数，既可以更改通道参数以后调用 kd_mpi_dpu_set_chn_attr 来使更改生效，也可以更改设备参数以后调用 kd_mpi_dpu_set_dev_attr 来使更改生效。如果只更改了通道参数，那么调用 kd_mpi_dpu_set_chn_attr 效率更高。
- 模板图结构体中包含了从配置文件中解析出来的模板图的虚拟地址和物理地址，以及模板图的大小。
【举例】
无
【相关主题】
2.1.4 kd_mpi_dpu_set_dev_attr
【描述】
配置 dpu 设备属性。
【语法】
k_s32 kd_mpi_dpu_set_dev_attr(k_dpu_dev_attr_t *attr);
【参数】
| 参数名称 | 描述 | 输入/输出 |
|---|---|---|
| attr | dpu 设备属性 | 输入 |
【返回值】
| 返回值 | 描述 |
|---|---|
| 0 | 成功 |
| 非0 | 失败，其值参见错误码 |
【芯片差异】
无
【需求】
- 头文件：mpi_dpu_api.h
- 库文件：libdpu.a
【注意】
- 只有对 dpu 设备初始化以后才可以调用此函数配置 dpu 设备属性。
- 在首次配置 dpu 设备属性时，应该将 attr 中的 tytz_temp_recfg 和 align_depth_recfg 配置为 K_TRUE，以使 dpu 加载对应参数。后续更改 dpu 设备属性时，如果对应的长周期参数没有改变，将这两个成员配置为 K_FALSE，可以节省 dpu 再次加载长周期参数的时间。
【举例】
无
【相关主题】
2.1.5 kd_mpi_dpu_get_dev_attr
【描述】
获取 dpu 设备属性。
【语法】
k_s32 kd_mpi_dpu_set_dev_attr(k_dpu_dev_attr_t *attr);
【参数】
| 参数名称 | 描述 | 输入/输出 |
|---|---|---|
| attr | dpu 设备属性 | 输出 |
【返回值】
| 返回值 | 描述 |
|---|---|
| 0 | 成功 |
| 非0 | 失败，其值参见错误码 |
【芯片差异】
无
【需求】
- 头文件：mpi_dpu_api.h
- 库文件：libdpu.a
【注意】
无
【举例】
无
【相关主题】
2.1.6 kd_mpi_dpu_set_ref_image
【描述】
配置 dpu 参考图。
【语法】
k_s32 kd_mpi_dpu_set_ref_image(const k_char *ref_path);
【参数】
| 参数名称 | 描述 | 输入/输出 |
|---|---|---|
| ref_path | 参考图路径 | 输入 |
【返回值】
| 返回值 | 描述 |
|---|---|
| 0 | 成功 |
| 非0 | 失败，其值参见错误码 |
【芯片差异】
无
【需求】
- 头文件：mpi_dpu_api.h
- 库文件：libdpu.a
【注意】
- 需要在配置 dpu 设备属性以后再调用此函数配置参考图。
【举例】
无
【相关主题】
无
2.1.7 kd_mpi_dpu_set_processed_ref_image
【描述】
配置离线处理后的 dpu 参考图。
【语法】
k_s32 kd_mpi_dpu_set_processed_ref_image(const k_char *ref_path);
【参数】
| 参数名称 | 描述 | 输入/输出 |
|---|---|---|
| ref_path | 处理后的参考图路径 | 输入 |
【返回值】
| 返回值 | 描述 |
|---|---|
| 0 | 成功 |
| 非0 | 失败，其值参见错误码 |
【芯片差异】
无
【需求】
- 头文件：mpi_dpu_api.h
- 库文件：libdpu.a
【注意】
- 需要在配置 dpu 设备属性以后再调用此函数配置参考图，配置的参考图需要离线处理好，调用此函数可以比 kd_mpi_dpu_set_ref_image 节省约 70ms 时间。
【举例】
无
【相关主题】
无
2.1.8 kd_mpi_dpu_set_template_image
【描述】
配置 dpu 模板图
【语法】
k_s32 kd_mpi_dpu_set_template_image(k_dpu_user_space_t *temp_space);
【参数】
| 参数名称 | 描述 | 输入/输出 |
|---|---|---|
| temp_space | 模板图结构体。 | 输入 |
【返回值】
| 返回值 | 描述 |
|---|---|
| 0 | 成功 |
| 非0 | 失败，其值参见错误码 |
【芯片差异】
无
【需求】
- 头文件：mpi_dpu_api.h
- 库文件：libdpu.a
【注意】
- 需要在配置 dpu 设备属性以后再调用此函数配置参考图。
- temp_space 需要在 kd_mpi_dpu_parse_file 时作为参数传入，以从配置文件中获取模板图信息。
【举例】
无
【相关主题】
k_dpu_user_space_t kd_mpi_dpu_parse_file
2.1.9 kd_mpi_dpu_start_dev
【描述】
启动 dpu 设备
【语法】
k_s32 kd_mpi_dpu_start_dev();
【参数】
| 参数名称 | 描述 | 输入/输出 |
|---|---|---|
| 无 | 无 | 无 |
【返回值】
| 返回值 | 描述 |
|---|---|
| 0 | 成功 |
| 非0 | 失败，其值参见错误码 |
【芯片差异】
无
【需求】
- 头文件：mpi_dpu_api.h
- 库文件：libdpu.a
【注意】
无
【举例】
无
【相关主题】
无
2.1.10 kd_mpi_dpu_set_chn_attr
【描述】
配置 dpu 通道属性
【语法】
k_s32 kd_mpi_dpu_set_chn_attr(k_dpu_chn_lcn_attr_t *lcn_attr, k_dpu_chn_ir_attr_t *ir_attr);
【参数】
| 参数名称 | 描述 | 输入/输出 |
|---|---|---|
| lcn_attr | 散斑图通道属性。 | 输入 |
| ir_attr | 红外图通道属性。 | 输入 |
【返回值】
| 返回值 | 描述 |
|---|---|
| 0 | 成功 |
| 非0 | 失败，其值参见错误码 |
【芯片差异】
无
【需求】
- 头文件：mpi_dpu_api.h
- 库文件：libdpu.a
【注意】
- 当前 dpu 设备一共有两个通道：0 和 1。通过配置 lcn_attr->chn_num 和 ir_attr->chn_num（如果开启了红外图通道） 来指明散斑图和红外图各自的输入输出通道。
- 在首次启动 dpu 设备 kd_mpi_dpu_start_dev 以后，应该调用此函数来配置通道属性，其中散斑图通道必须配置，红外图通道如果没有开启可以不配置（配置为 NULL）。
- 在运行过程中如果只需要更改某个通道的属性，可以只传入该通道的结构体参数，另一个通道的参数可以为 NULL。也可以同时传入两个通道的参数。如果两个通道的参数都为 NULL，则该次配置是不会生效的。
【举例】
无
【相关主题】
k_dpu_chn_lcn_attr_t k_dpu_chn_ir_attr_t
2.1.11 kd_mpi_dpu_get_chn_attr
【描述】
获取 dpu 通道属性。
【语法】
k_s32 kd_mpi_dpu_get_chn_attr(k_dpu_chn_lcn_attr_t *lcn_attr, k_dpu_chn_ir_attr_t *ir_attr);
【参数】
| 参数名称 | 描述 | 输入/输出 |
|---|---|---|
| lcn_attr | 散斑图通道属性。 | 输出 |
| ir_attr | 红外图通道属性。 | 输出 |
【返回值】
| 返回值 | 描述 |
|---|---|
| 0 | 成功 |
| 非0 | 失败，其值参见错误码 |
【芯片差异】
无
【需求】
- 头文件：mpi_dpu_api.h
- 库文件：libdpu.a
【注意】
无
【举例】
无
【相关主题】
k_dpu_chn_lcn_attr_t k_dpu_chn_ir_attr_t
2.1.12 kd_mpi_dpu_start_chn
【描述】
启动 dpu 通道
【语法】
k_s32 kd_mpi_dpu_start_chn(k_u32 chn_num);
【参数】
| 参数名称 | 描述 | 输入/输出 |
|---|---|---|
| chn_num | 通道号 | 输入 |
【返回值】
| 返回值 | 描述 |
|---|---|
| 0 | 成功 |
| 非0 | 失败，其值参见错误码 |
【芯片差异】
无
【需求】
- 头文件：mpi_dpu_api.h
- 库文件：libdpu.a
【注意】
- 通道号应该为 0 或 1。
【举例】
无
【相关主题】
无
2.1.13 kd_mpi_dpu_stop_chn
【描述】
停止 dpu 通道
【语法】
k_s32 kd_mpi_dpu_stop_chn(k_u32 chn_num);
【参数】
| 参数名称 | 描述 | 输入/输出 |
|---|---|---|
| chn_num | 通道号 | 输入 |
【返回值】
| 返回值 | 描述 |
|---|---|
| 0 | 成功 |
| 非0 | 失败，其值参见错误码 |
【芯片差异】
无
【需求】
- 头文件：mpi_dpu_api.h
- 库文件：libdpu.a
【注意】
- 通道号应为 0 或 1。
【举例】
无
【相关主题】
无
2.1.14 kd_mpi_dpu_send_frame
【描述】
在非绑定模式下，向 dpu 发送一帧数据。
【语法】
k_s32 kd_mpi_dpu_send_frame(k_u32 chn_num, k_u64 addr, k_s32 s32_millisec);
【参数】
| 参数名称 | 描述 | 输入/输出 |
|---|---|---|
| chn_num | 通道号 | 输入 |
| addr | 发送数据的物理地址 | 输入 |
| s32_millisec | 等待时间。 当此参数设置为 -1 时，阻塞模式，直到发送成功才会返回； 当此参数设置为 0 时，非阻塞模式，发送成功立即返回零，发送失败立即返回其他值，具体失败信息参考 dpu 错误码； | 输入 |
【返回值】
| 返回值 | 描述 |
|---|---|
| 0 | 成功 |
| 非0 | 失败，其值参见错误码 |
【芯片差异】
无
【需求】
- 头文件：mpi_dpu_api.h
- 库文件：libdpu.a
【注意】
- 如果同时开启了散斑图和红外图通路，需要红外图和散斑图严格交叉输入。
【举例】
无
【相关主题】
无
2.1.15 kd_mpi_dpu_get_frame
【描述】
从 dpu 获取一帧数据。
【语法】
k_s32 kd_mpi_dpu_get_frame(k_u32 chn_num, k_dpu_chn_result_u *result, k_s32 s32_millisec);
【参数】
| 参数名称 | 描述 | 输入/输出 |
|---|---|---|
| chn_num | 通道号 | 输入 |
| result | dpu 输出结果联合体，其成员变量分别是 k_dpu_chn_lcn_result_t 和 k_dpu_chn_ir_result_t 。选择哪个成员作为该通道的输出结果由用户根据 kd_mpi_dpu_set_chn_attr 的配置来自行决定。 | 输出 |
| s32_millisec | 等待时间。 当此参数设置为 -1 时，阻塞模式，直到获取成功才会返回； 当此参数设置为 0 时，非阻塞模式，获取成功立即返回零，获取失败立即返回其他值，具体失败信息参考 dpu 错误码； | 输入 |
【返回值】
| 返回值 | 描述 |
|---|---|
| 0 | 成功 |
| 非0 | 失败，其值参见错误码 |
【芯片差异】
无
【需求】
- 头文件：mpi_dpu_api.h
- 库文件：libdpu.a
【注意】
- 如果同时开启了红外图和散斑图，注意及时取走两个通道的输出结果，否则 buffer 中的结果会溢出造成无法继续输入的情况。
【举例】
无
【相关主题】
k_dpu_chn_result_u k_dpu_chn_lcn_result_t k_dpu_chn_ir_result_t k_dpu_disp_out_t k_dpu_depth_out_t k_dpu_ir_out_t k_dpu_qlt_out_t
2.1.16 kd_mpi_dpu_release_frame
【描述】
在非绑定模式下，释放已经获取的结果。
【语法】
k_s32 kd_mpi_dpu_release_frame();
【参数】
无
【返回值】
| 返回值 | 描述 |
|---|---|
| 0 | 成功 |
| 非0 | 失败，其值参见错误码 |
【芯片差异】
无
【需求】
- 头文件：mpi_dpu_api.h
- 库文件：libdpu.a
【注意】
- 此函数会依次释放 buffer 中的数据，先生成的结果先释放。目前 dpu buffer 为 3，使用完 kd_mpi_dpu_get_frame 获取的结果以后请尽快释放。
【举例】
无
【相关主题】
无
3. 数据类型
3.1 公共数据类型
本模块有如下数据类型：
- k_dpu_init_t
- k_dpu_dev_param_t
- k_dpu_lcn_param_t
- k_dpu_ir_param_t
- k_dpu_user_space_t
- k_dpu_dev_attr_t
- k_dpu_chn_lcn_attr_t
- k_dpu_chn_ir_attr_t
- k_dpu_chn_result_u
- k_dpu_chn_lcn_result_t
- k_dpu_chn_ir_result_t
- k_dpu_disp_out_t
- k_dpu_depth_out_t
- k_dpu_ir_out_t
- k_dpu_qlt_out_t
3.1.1 k_dpu_init_t
【说明】
dpu 设备初始化结构体
【定义】
typedef struct {
k_u32 start_num;
k_u32 buffer_num;
} k_dpu_init_t;
【成员】
| 成员名称 | 描述 |
|---|---|
| start_num | dpu 设备起始帧号（即 dpu 计算出来的第一帧的帧号）。 |
| buffer_num | dpu 缓存 buffer 的数量，至少为 1 |
【注意事项】
无
【相关数据类型及接口】
3.1.2 k_dpu_dev_param_t
【说明】
dpu 设备参数结构体。
【定义】
typedef struct
{
k_dpu_long_parameter_t lpp;
k_dpu_short_parameter_t spp;
} k_dpu_dev_param_t;
【成员】
| 成员名称 | 描述 |
|---|---|
| lpp | dpu 长周期参数结构体 |
| spp | dpu 短周期参数结构体 |
【注意事项】
- 用户需要对长周期参数中的值进行改变时，应该使用虚拟地址成员变量。
【相关数据类型及接口】
k_dpu_long_parameter_t kd_mpi_dpu_parse_file
3.1.3 k_dpu_lcn_param_t
【说明】
散斑图通道参数结构体。
【定义】
typedef struct {
k_u8 matching_length_left_p0;
k_u8 matching_length_right_p0;
float image_check_match_threshold;
float depth_p1;
float depth_p2;
float depth_precision;
} k_dpu_lcn_param_t;
【成员】
| 成员名称 | 描述 |
|---|---|
| matching_length_left_p0 | 粗搜索：视差计算向左搜索范围，取值：0~256，整型 |
| matching_length_right_p0 | 粗搜索：视差计算向右搜索范围，取值：0~256，整型 |
| image_check_match_threshold | 散斑图质量评定：模板匹配阈值，取值范围：0.0~1.0，浮点型：0.01精度 |
| depth_p1 | 视差转深度：深度数值计算系数p1，取值范围：0.0~50000.0，浮点型：0.01精度 |
| depth_p2 | 视差转深度：深度数值计算系数p2，取值范围：-5.0~100.0，浮点型：0.01精度 |
| depth_precision | 视差转深度：深度数值精度（倍数），取值范围：0.0~100.0，浮点型：0.1精度 |
【注意事项】
- 此通道结构体参数是设备结构体参数的子集，如果已经配置了设备参数，且通道参数和设备参数相同，可以不配置通道参数。
【相关数据类型及接口】
3.1.4 k_dpu_ir_param_t
【说明】
红外图通道参数结构体。
【定义】
typedef struct {
float depth_k1;
float depth_k2;
float tz;
} k_dpu_ir_param_t;
【成员】
| 成员名称 | 描述 |
|---|---|
| depth_k1 | 直接完全对应一个寄存器。三图对齐：深度数值计算系数k1，取值范围：2e-4~1e-2，浮点型：1e-5精度 |
| depth_k2 | 直接完全对应一个寄存器。三图对齐：深度数值计算系数k2，取值范围：0.5~1.5，浮点型：0.001精度 |
| tz | 直接完全对应一个寄存器。三图对齐：投射器z方向偏移量（毫米），取值范围：-5.0~5.0，浮点型：0.001精度 |
【注意事项】
- 此通道结构体参数是设备结构体参数的子集，如果已经配置了设备参数，且通道参数和设备参数相同，可以不配置通道参数。
【相关数据类型及接口】
3.1.5 k_dpu_user_space_t
【说明】
用户获取模板图结构体参数。
【定义】
typedef struct {
k_bool used;
k_u32 size;
k_u64 phys_addr;
void *virt_addr;
} k_dpu_user_space_t;
【成员】
| 成员名称 | 描述 |
|---|---|
| used | 用户不需要关注 |
| size | 用户获取的模板图的大小 |
| phys_addr | 模板图的物理地址 |
| virt_addr | 模板图的虚拟地址 |
【注意事项】
无
【相关数据类型及接口】
3.1.6 k_dpu_dev_attr_t
【说明】
配置 dpu 设备属性结构体。
【定义】
typedef struct {
k_dpu_mode_e mode;
k_bool tytz_temp_recfg;
k_bool align_depth_recfg;
k_bool ir_never_open;
k_u32 param_valid;
k_dpu_dev_param_t dev_param;
} k_dpu_dev_attr_t;
【成员】
| 成员名称 | 描述 |
|---|---|
| mode | dpu 运行模式，包括绑定模式和非绑定模式。 |
| tytz_temp_recfg | 是否更新加载 SAD 温度补偿参数和 TyTz 行补偿计算算数。当此标志位为 K_FALSE 时表明不更新，当此标志位为 K_TRUE 时表明更新。 |
| align_depth_recfg | 是否更新加载三图对齐/转深度计算参数。当此标志位为 K_FALSE 时表明不更新，当此标志位为 K_TRUE 时表明更新。 |
| ir_never_open | vb 池是在启动 dpu 设备时配置的，直到暂停 dpu 设备时释放。其大小在启动设备时进行初始化，因此在启动设备时就预留了深度/视差图、红外输出、质量检测、粗细列视差、初始行列式差共五部分的空间。用户可以在使用周期内通过 dev_param.spp.flag_align 来选择是否开启三图对齐。 如果在整个使用周期内都不会有红外图的输出，就不需要为红外图预留空间。配置为 K_TRUE 表明不需要为红外图输出预留空间，配置为 K_FALSE 表明需要为红外图输出预留空间。 |
| param_valid | 用户配置 dpu 设备属性时，将此成员设置为一个任意的非零值，当设备属性生效时，会在对应生效的帧的输出结果中返回该任意值。 |
| dev_param | dpu 设备参数结构体。 |
【注意事项 】
- 在首次配置 dpu 设备属性时，应该将 tytz_temp_recfg 和 align_depth_recfg 配置为 K_TRUE，以使 dpu 加载对应参数。
【相关数据类型及接口】
k_dpu_dev_param_t kd_mpi_dpu_set_dev_attr
3.1.7 k_dpu_chn_lcn_attr_t
【说明】
配置散斑图通道属性结构体
【定义】
typedef struct {
k_u8 param_valid;
k_s32 chn_num;
k_dpu_lcn_param_t lcn_param;
} k_dpu_chn_lcn_attr_t;
【成员】
| 成员名称 | 描述 |
|---|---|
| param_valid | 用户配置散斑图通道属性时，将此成员设置为一个任意的非零值，当设备属性生效时，会在对应生效的帧的输出结果中返回该任意值。 |
| chn_num | 通道号。当前 dpu 设备一共有两个通道，用户可以将此通道号设为 0 或 1，散斑图通道将在对应通道中输入输出。如果开启了红外图通道，此通道号应该与红外图通道号不同。 |
| lcn_param | 散斑图通道参数。 |
【注意事项】
无
【相关数据类型及接口】
3.1.8 k_dpu_chn_ir_attr_t
【说明】
配置红外图通道属性 结构体
【定义】
typedef struct {
k_u8 param_valid;
k_s32 chn_num;
k_dpu_ir_param_t ir_param;
} k_dpu_chn_ir_attr_t;
【成员】
| 成员名称 | 描述 |
|---|---|
| param_valid | 用户配置散斑图通道属性时，将此成员设置为一个任意的非零值，当设备属性生效时，会在对应生效的帧的输出结果中返回该任意值。 |
| chn_num | 通道号。当前 dpu 设备一共有两个通道，用户可以将此通道号设为 0 或 1，红外图通道将在对应通道中输入输出。此通道号应该与散斑图通道号不同。 |
| ir_param | 红外图通道参数。 |
【注意事项】
无
【相关数据类型及接口】
3.1.9 k_dpu_chn_result_u
【说明】
获取 dpu 输出结果的联合体
【定义】
typedef union {
k_dpu_chn_lcn_result_t lcn_result;
k_dpu_chn_ir_result_t ir_result;
} k_dpu_chn_result_u;
【成员】
| 成员名称 | 描述 |
|---|---|
| lcn_result | 散斑图通道输出结果结构体。k_dpu_chn_lcn_result_t |
| ir_result | 红外图通道输出结果结构体。k_dpu_chn_ir_result_t |
【注意事项】
- 用户选择哪个成员作为输出结果需要根据用户自己的配置来选择。在 kd_mpi_dpu_set_chn_attr 中用户 配置了通道号和通道类型的对应关系。
【相关数据类型及接口】
k_dpu_chn_lcn_result_t k_dpu_chn_ir_result_t kd_mpi_dpu_get_frame
3.1.10 k_dpu_chn_lcn_result_t
【说明】
dpu 散斑图通道输出结果的结构体
【定义】
typedef struct {
k_u32 time_ref;
k_u64 pts;
k_dpu_disp_out_t disp_out;
k_dpu_depth_out_t depth_out;
k_dpu_qlt_out_t qlt_out;
k_dpu_param_flag_t flag;
} k_dpu_chn_lcn_result_t;
【成员】
| 成员名称 | 描述 |
|---|---|
| pts | 时间戳，绑定模式下有效。 |
| disp_out | 视差图输出结果结构体。 |
| depth_out | 深度图输出结果结构体。 |
| qlt_out | 质量检测输出结果结构体。包括质量检测结果、粗细_列视差（初始分辨率）结果、初始行列式差结果。 |
| flag | 此结构体用来标记用户配置的参数在哪一帧生效了。结构体中包含了 k_dpu_dev_attr_t、k_dpu_chn_lcn_attr_t、k_dpu_chn_ir_attr_t 中的 param_valid 变量。 |
【注意事项】
无
【相关数据类型及接口】
k_dpu_disp_out_t k_dpu_depth_out_t k_dpu_qlt_out_t kd_mpi_dpu_get_frame
3.1.11 k_dpu_chn_ir_result_t
【说明】
dpu 红外图通道输出结果的结构体
【定义】
typedef struct {
k_u32 time_ref;
k_u64 pts;
k_dpu_ir_out_t ir_out;
k_dpu_param_flag_t flag;
} k_dpu_chn_ir_result_t;
【成员】
| 成员名称 | 描述 |
|---|---|
| pts | 时间戳，绑定模式下有效。 |
| ir_out | 红外图输出结果结构体。 |
| flag | 此结构体用来标记用户配置的参数在哪一帧生效了。结构体中 包含了 k_dpu_dev_attr_t、k_dpu_chn_lcn_attr_t、k_dpu_chn_ir_attr_t 中的 param_valid 变量。 |
【注意事项】
无
【相关数据类型及接口】
k_dpu_ir_out_t kd_mpi_dpu_get_frame
3.1.12 k_dpu_disp_out_t
【说明】
视差图输出结果的结构体
【定义】
typedef struct {
k_bool valid;
k_u32 length;
k_u64 disp_phys_addr;
k_u64 disp_virt_addr;
} k_dpu_disp_out_t;
【成员】
| 成员名称 | 描述 |
|---|---|
| valid | K_TRUE：表明输出结果有效； K_FALSE：表明输出结果无效。 |
| length | 输出结果长度。 |
| disp_phys_addr | 视差图输出结果物理地址。 |
| disp_virt_addr | 视差图输出结果虚拟地址。 |
【注意事项】
无
【相关数据类型及接口】
k_dpu_chn_lcn_result_t kd_mpi_dpu_get_frame
3.1.13 k_dpu_depth_out_t
【说 明】
深度图输出结果的结构体
【定义】
typedef struct {
k_bool valid;
k_u32 length;
k_u64 depth_phys_addr;
k_u64 depth_virt_addr;
} k_dpu_depth_out_t;
【成员】
| 成员名称 | 描述 |
|---|---|
| valid | K_TRUE：表明输出结果有效； K_FALSE：表明输出结果无效。 |
| length | 输出结果长度。 |
| depth_phys_addr | 深度图输出结果物理地址。 |
| depth_virt_addr | 深度图输出结果虚拟地址。 |
【注意事项】
无
【相关数据类型及接口】
k_dpu_chn_lcn_result_t kd_mpi_dpu_get_frame
3.1.14 k_dpu_ir_out_t
【说明】
红外图输出结果的结构体
【定义】
typedef struct {
k_bool valid;
k_u32 length;
k_u64 ir_phys_addr;
k_u64 ir_virt_addr;
} k_dpu_ir_out_t;
【成员】
| 成员名称 | 描述 |
|---|---|
| valid | K_TRUE：表明输出结果有效； K_FALSE：表明输出结果无效。 |
| length | 输出结果长度。 |
| ir_phys_addr | 红外图输出 结果物理地址。 |
| ir_virt_addr | 红外图输出结果虚拟地址。 |
【注意事项】
无
【相关数据类型及接口】
k_dpu_chn_ir_result_t kd_mpi_dpu_get_frame
3.1.15 k_dpu_qlt_out_t
【说明】
质量检测输出结果的结构体
【定义】
typedef struct {
k_bool valid;
k_u32 qlt_length;
k_u32 sad_disp_length;
k_u32 init_sad_disp_length;
k_u64 qlt_phys_addr;
k_u64 qlt_virt_addr;
k_u64 sad_disp_phys_addr;
k_u64 sad_disp_virt_addr;
k_u64 init_sad_disp_phys_addr;
k_u64 init_sad_disp_virt_addr;
} k_dpu_qlt_out_t;
【成员】
| 成员名称 | 描述 |
|---|---|
| valid | K_TRUE：表明输出结果有效； K_FALSE：表明输出结果无效。 |
| qlt_length | 质量检测输出结果长度。 |
| sad_disp_length | 粗细列视差（初始分辨率）输出结果长度。 |
| init_sad_disp_length | 初始行列式差输出结果长度。 |
| qlt_phys_addr | 质量检测输出结果物理地址。 |
| qlt_virt_addr | 质量检测输出结果虚拟地址。 |
| sad_disp_phys_addr | 粗细列视差（初始分辨率）输出结果物理地址。 |
| sad_disp_virt_addr | 粗细列视差（初始分辨率）输出结果虚拟地址。 |
| init_sad_disp_phys_addr | 初始行列式差输出结果物理地址。 |
| init_sad_disp_virt_addr | 初始行列式差输出结果虚拟地址。 |
【注意事项】
无
【相关数据类型及接口】
k_dpu_chn_lcn_result_t kd_mpi_dpu_get_frame
3.2 长短周期参数类型
本模块有如下数据类型：
3.2.1 k_dpu_long_parameter_t
【说明】
dpu 长周期参数结构体
【定义】
typedef struct
{
/* virtual address */
float* row_start_p0; /**< 粗搜索：TyTz行偏差补偿后起始行序号指针，数组最大长度：1920，取值范围：0.0-1920.0，浮点型：0.02精度 */
float* row_end_p0; /**< 粗搜索：TyTz行偏差补偿后末尾行序号指针，数组最大长度：1920，取值范围：0.0-1920.0，浮点型：0.02精度 */
float* row_start_p1; /**< 细搜索：TyTz行偏差补偿后起始行序号指针，数组最大长度：1920，取值范围：0.0-1920.0，浮点型：0.02精度 */
float* row_end_p1; /**< 细搜索：TyTz行偏差补偿后末尾行序号指针，数组最大长度：1920，取值范围：0.0-1920.0，浮点型：0.02精度 */
k_u8 *row_start; /**< TyTz行偏差补偿后起始行序号指针，数组最大长度：1920，取值范围：0-1920，整型 */
k_u8 *row_end; /**< TyTz行偏差补偿后末尾行序号指针，数组最大长度：1920，取值范围：0-1920，整型 */
float *row_offset; /**< 温度行偏差补偿量指针，数组最大长度：1920，取值范围：-32.0~32.0，浮点型：0.02精度 */
float *col_offset; /**< 温度列偏差补偿量指针，数组最大长度：1280，取值范围：-32.0~32.0，浮点型：0.02精度 */
k_u8 *row_start_disp; /**< 视差图对齐计算时，每一切块起始行序号指针，数组最大长度：1920，取值范围：0-1920，整型 */
k_u8 *row_end_disp; /**< 视差图对齐计算时，每一切块末尾行序号指针，数组最大长度：1920，取值范围：0-1920，整型 */
k_u8 *row_start_ir; /**< 红外图对齐计算时，每一切块起始行序号指针，数组最大长度：1920，取值范围：0-1920，整型 */
k_u8 *row_end_ir; /**< 红外图对齐计算时，每一切块末尾行序号指针，数组最大长度：1920，取值范围：0-1920，整型 */
float *depth_K; /**< 深度数值计算参数K指针，数组最大长度：1280，取值范围：500.0~1500000.0，浮点型：0.1精度 */
float *align_A; /**< 视差对齐参数A指针，数组最大长度：1280，取值范围：-10.0~10.0，浮点型：0.001精度 */
float *align_B; /**< 视差对 齐参数B指针，数组最大长度：1280，取值范围：-10.0~10.0，浮点型：0.001精度 */
float *align_C; /**< 视差对齐参数C指针，数组最大长度：1280，取值范围：-10.0~10.0，浮点型：0.001精度 */
float *align_D; /**< 视差对齐参数D指针，数组最大长度：1280，取值范围：-10.0~10.0，浮点型：0.001精度 */
float *align_E; /**< 视差对齐参数E指针，数组最大长度：1280，取值范围：-10.0~10.0，浮点型：0.001精度 */
float *align_F; /**< 视差对齐参数F指针，数组最大长度：1280，取值范围：-10.0~10.0，浮点型：0.001精度 */
float *depth_P; /**< 深度数值计算参数P指针，数组最大长度：1280，取值范围：5e-7~2e-3，浮点型：1e-8精度 */
k_u16* block_row_start_ir; /**< 三图对齐：红外图对齐时，每一分块起始行序号指针，数组最大长度：1920，取值范围：0-1920，整型 */
k_u16* block_row_end_ir; /**< 三图对齐：红外图对齐时，每一分块末尾行序号指针，数组最大长度：1920，取值范围：0-1920，整型 */
k_u16* block_row_start_disp; /**< 三图对齐：视差图对齐时，每一分块起始行序号指针，数组最大长度：1920，取值范围：0-1920，整型 */
k_u16* block_row_end_disp; /**< 三图对齐：视差图对齐时，每一分块末尾行序号指针，数组最大长度：1920，取值范围：0-1920，整型 */
float mat_R[3]; /**< 三图对齐：红外相机相对彩色 相机旋转矩阵，3*1数组，值域范围：-1.0~1.0，浮点型：0.01精度 */
float mat_T[3]; /**< 三图对齐：红外相机相对彩色相机平移矩阵，3*1数组，值域范围：-250.0~250.0，浮点型：0.01精度 */
/* physical address */
k_u64 row_start_p0_phys; /**< 粗搜索：TyTz行偏差补偿后起始行序号指针，数组最大长度：1920，取值范围：0.0-1920.0，浮点型：0.02精度 */
k_u64 row_end_p0_phys; /**< 粗搜索：TyTz行偏差补偿后末尾行序号指针，数组最大长度：1920，取值范围：0.0-1920.0，浮点型：0.02精度 */
k_u64 row_start_p1_phys; /**< 细搜索：TyTz行偏差补偿后起始行序号指针，数组最大长度：1920，取值范围：0.0-1920.0，浮点型：0.02精度 */
k_u64 row_end_p1_phys; /**< 细搜索：TyTz行偏差补偿后末尾行序号指针，数组最大长度：1920，取值范围：0.0-1920.0，浮点型：0.02精度 */
k_u64 row_start_phys; /**< TyTz行偏差补偿后起始行序号指针，数组最大长度：1920，取值范围：0-1920，整型 */
k_u64 row_end_phys; /**< TyTz行偏差补偿后末尾行序号指针，数组最大长度：1920，取值范围：0-1920，整型 */
k_u64 row_offset_phys; /**< 温度行偏差补偿量指针，数组最大长度：1920，取值范围：-32.0~32.0，浮点型：0.02精度 */
k_u64 col_offset_phys; /**< 温度列偏差补偿量指针，数组最大长度：1280，取值范围：-32.0~32.0，浮点型：0.02精度 */
k_u64 row_start_disp_phys; /**< 视差图对齐计算时，每一切块起始行序号指针，数组最大长度：1920，取值范围：0-1920，整型 */
k_u64 row_end_disp_phys; /**< 视差图对齐计算时，每一切块末尾行序号指针，数组最大长度：1920，取值范围：0-1920，整型 */
k_u64 row_start_ir_phys; /**< 红外图对齐计算时，每一切块起始行序号指针，数组最大长度：1920，取值范围：0-1920，整型 */
k_u64 row_end_ir_phys; /**< 红外图对齐计算时，每一切块末尾行序号指针，数组最大长度：1920，取值范围：0-1920，整型 */
k_u64 depth_K_phys; /**< 深度数值计算参数K指针，数组最大长度：1280，取值范围：500.0~1500000.0，浮点型：0.1精度 */
k_u64 align_A_phys; /**< 视差对齐参数A指针，数组最大长度：1280，取值范围：-10.0~10.0，浮点型：0.001精度 */
k_u64 align_B_phys; /**< 视差对齐参数B指针，数组最大长度：1280，取值范围：-10.0~10.0，浮点型：0.001精 度 */
k_u64 align_C_phys; /**< 视差对齐参数C指针，数组最大长度：1280，取值范围：-10.0~10.0，浮点型：0.001精度 */
k_u64 align_D_phys; /**< 视差对齐参数D指针，数组最大长度：1280，取值范围：-10.0~10.0，浮点型：0.001精度 */
k_u64 align_E_phys; /**< 视差对齐参数E指针，数组最大长度：1280，取值范围：-10.0~10.0，浮点型：0.001精度 */
k_u64 align_F_phys; /**< 视差对齐参数F指针，数组最大长度：1280，取值范围：-10.0~10.0，浮点型：0.001精度 */
k_u64 depth_P_phys; /**< 深度数值计算参数P指针，数组最大长度：1280，取值范围：5e-7~2e-3，浮点型：1e-8精度 */
k_u64 block_row_start_ir_phys; /**< 三图对齐：红外图对齐时，每一分块起始行序号指针，数组最大长度：1920，取值范围：0-1920，整型 */
k_u64 block_row_end_ir_phys; /**< 三图对齐：红外图对齐时，每一分块末尾行序号指针，数组最大长度：1920，取值范围：0-1920，整型 */
k_u64 block_row_start_disp_phys;/**< 三图对齐：视差图对齐时，每一分块起始行序号指针，数组最大长度：1920，取值范围：0-1920，整型 */
k_u64 block_row_end_disp_phys; /**< 三图对齐：视差图对齐时，每一分块末尾行序号指针，数组最大长度：1920，取值范围：0-1920，整 型 */
k_u64 mat_R_phys; /**< 三图对齐：红外相机相对彩色相机旋转矩阵，3*1数组，值域范围：-1.0~1.0，浮点型：0.01精度 */
k_u64 mat_T_phys; /**< 三图对齐：红外相机相对彩色相机平移矩阵，3*1数组，值域范围：-250.0~250.0，浮点型：0.01精度 */
} k_dpu_long_parameter_t;
【注意事项】
- 用户需要对长周期参数中的值进行改变时，应该使用虚拟地址成员变量。
【相关数据类型及接口】
k_dpu_dev_param_t kd_mpi_dpu_parse_file kd_mpi_dpu_set_dev_attr
3.2.2 k_dpu_short_parameter_t
【说明】
dpu 短周期参数结构体
【定义】
短周期参数成员过多，不在此展示，可以参见 K230_SDK 中 k_dpu_comm.h 中的结构体 k_dpu_short_parameter_t。
【注意事项】
无
【相关数据类型及接口】
k_dpu_dev_param_t kd_mpi_dpu_set_dev_attr kd_mpi_dpu_get_dev_attr
4. 错误码
4.1 dpu 错误码
表 41
| 错误代码 | 宏定义 | 描述 |
|---|---|---|
| 0xa00118001 | K_ERR_DPU_INVALID_DEVID | 无效的设备号 |
| 0xa00118002 | K_ERR_DPU_INVALID_CHNID | 无效的通道号 |
| 0xa00118003 | K_ERR_DPU_ILLEGAL_PARAM | 参数错误 |
| 0xa00118004 | K_ERR_DPU_EXIST | DPU 设备已经存在 |
| 0xa00118005 | K_ERR_DPU_UNEXIST | DPU 设备不存在 |
| 0xa00118006 | K_ERR_DPU_NULL_PTR | 空指针错误 |
| 0xa00118007 | K_ERR_DPU_NOT_CONFIG | 尚未配置 DPU |
| 0xa00118008 | K_ERR_DPU_NOT_SUPPORT | 不支持的功能 |
| 0xa00118009 | K_ERR_DPU_NOT_PERM | 操作不允许 |
| 0xa0011800c | K_ERR_DPU_NOMEM | 分配内存失败，如系统内存不足 |
| 0xa0011800d | K_ERR_DPU_NOBUF | BUFF 不足 |
| 0xa0011800e | K_ERR_DPU_BUF_EMPTY | BUFF 为空 |
| 0xa0011800f | K_ERR_DPU_BUF_FULL | BUFF 已满 |
| 0xa00118010 | K_ERR_DPU_NOTREADY | 设备未就绪 |
| 0xa00118011 | K_ERR_DPU_BADADDR | 错误的地址 |
| 0xa00118012 | K_ERR_DPU_BUSY | DPU 处与忙状态 |
5. 调试信息
5.1 概述
调试信息采用了 proc 文件系统，可实时反映当前系统的运行状态，所记录的信息可供问题定位及分析时使用
【文件目录】
/proc/
【文件清单】
| 文件名称 | 描述 |
|---|---|
| umap/dpu | 记录当前 dpu 模块的一些信息 |
5.2 调试信息
【调试信息】
----------------------DPU Device Information----------------------
--------------------Pathway Switch Information--------------------
downScale: false align: false
align_ir: false align_rgbCoord: false
depthout: false denoise: false
median_p0: false median_denoise: false
median_post: false median_ir: false
check: false
----------------------Image Size Information----------------------
width_speckle: 0 height_speckle: 0
width_color: 0 height_color: 0
width_output: 0 height_output: 0
---------------------Result Length Information--------------------
sad_disp_x: 0 init_sad_disp_xy: 0
quanlity_check: 0 ir: 0
disp/depth: 0
----------------------------Frame Count---------------------------
from open to close, dpu has send 0 frames
【通路选择信息】
| 参数 | 描述 |
|---|---|
| downScale | 是否粗搜索降分辨率 |
| align | 是否三图对齐 |
| align_ir | 是否红外图对齐 |
| align_rgbCoord | 是否视差数值对齐到彩色图坐标系 |
| depthout | 是否输出深度图 |
| denoise | 是否视差图去噪 |
| median_p0 | 是否粗搜索中值滤波 |
| median_denoise | 是否视差去 噪内部中值滤波 |
| median_post | 是否视差后处理/三图对齐视差图中值滤波 |
| median_ir | 是否三图对齐红外图中值滤波 |
| check | 是否物体散斑图质量检测及初始搜索 |
【图像大小信息】
| 参数 | 描述 |
|---|---|
| width_speckle | 原始散斑图/红外图宽度像素数 |
| height_speckle | 原始散斑图/红外图高度像素数 |
| width_color | 原始彩色图宽度像素数 |
| height_color | 原始彩色图高度像素数 |
| width_output | 输出视差图/深度图/红外图宽度像素数 |
| height_output | 输出视差图/深度图/红外图高度像素数 |
【结果长度信息】
| 参数 | 描述 |
|---|---|
| sad_disp_x | 粗细列视差（初始分辨率）结果长度 |
| init_sad_disp_xy | 初始行列视差输出结果长度 |
| quanlity_check | 质量检测结果长度 |
| ir | 红外图结果长度 |
| disp/depth | 视差图/深度图结果长度 |
调测信息需要在 dpu 运行过程中查看，dpu 结束运行以后，当前所有信息会重置为零。
6. demo 描述
6.1 dpu demo 简介
dpu demo 实现了绑定和非绑定两种模式。在 msh 中输入 /bin/sample_dpu.elf 执行非绑定模式，运行十帧后结束；在 msh 中输入 /bin/sample_dpu.elf BOUND 执行绑定模式，以 vvi 作为模拟上级不停的输入数据给 dpu，dpu 计算完成后显示信息。
6.2 Feature 说明
demo 中包含了初始化和删除 dpu，从配置文件解析参数，配置设备属性，配置通道属性，启动和暂停设备，启动和暂停通道，输入输出数据，pipeline 绑定等功能。
6.2.1 非绑定模式
通过调用 API 完成 dpu 设备的初始化，从配置文件中解析参数，根据解析参数配置设备属性，调用 API 设置参考图和模板图，启动 dpu 设备，配置散斑图和红外图通道属性，启动通道，循环输入十帧并比对结果后停止，停止通道，停止设备，删除设备。
6.2.2 绑定模式
通过调用 API 完成 dpu 设备的初始化，从配置文件中解析参数，绑定 vvi 和 dpu 通道，根据解析参数配置设备属性，调用 API 设置参考图和模板图，启动 dpu 设备，配置散斑图和红外图通道属性，启动 dpu 通道，启动 vvi 通道，vvi 作为模拟上级数据不停的输入数据给 dpu。用户输入 e 以后停止通道和设备。
6.2.3 编译和执行
编译和执行可以参考文档《K230 SDK Demo使用指南》。