前言¶

概述

本文档为SVP2.0平台_识别_分析方案开发的程序员而写，目的是供您在开发过程中查阅SVP2.0支持的各种参考信息，包括API、头文件、错误码等。

说明： 本文未有特殊说明，SS927V100与SS928V100内容完全一致。

产品版本

与本文档相对应的产品版本如下。

产品名称	产品版本
SS928	V100
SS927	V100

读者对象

本文档（本指南）主要适用于以下工程师：

技术支持工程师
软件开发工程师

符号约定

在本文中可能出现下列标志，它们所代表的含义如下。

符号	说明
	表示如不避免则将会导致死亡或严重伤害的具有高等级风险的危害。
	表示如不避免则可能导致死亡或严重伤害的具有中等级风险的危害。
	表示如不避免则可能导致轻微或中度伤害的具有低等级风险的危害。
	用于传递设备或环境安全警示信息。如不避免则可能会导致设备损坏、数据丢失、设备性能降低或其它不可预知的结果。 “须知”不涉及人身伤害。
	对正文中重点信息的补充说明。 “说明”不是安全警示信息，不涉及人身、设备及环境伤害信息。

修订记录

修订记录累积了每次文档更新的说明。最新版本的文档包含以前所有文档版本的更新内容。

版本	日期	修改描述
00B01	2025-09-15	第1次临时版本发布

MAU¶

概述¶

MAU（Matrix Arithmetic Unit）为_识别_分析系统中的矩阵算术单元。用户基于MAU进行矩阵运算，降低CPU占用。

功能描述¶

重要概念¶

句柄(handle)

用户在调用MAU API创建任务时，系统会为每个任务分配一个handle，用于标识不同的任务。
及时返回结果标志is_instant

用户在创建某个任务后，希望及时得到该任务完成的信息，则需要在创建该任务时，将is_instant设置为TD_TRUE。否则，如果用户不关心该任务是否完成，建议将is_instant设置为TD_FALSE，这样可以与后续任务组链执行，减少中断次数，提升性能。
查询(query)

用户根据系统返回的handle，调用ss_mpi_svp_mau_query可以查询对应算子任务是否完成。
跨度（stride）

一行的有效数据byte数目 + 为硬件快速跨越到下一行补齐的一些无效byte数目，如图1所示。注意不同的数据结构行存储表示的有效元素数目的变量不一样，且其度量跟stride不一定是一样的。
- ot_svp_blob行存储方向表示的有效元素数目变量是width。
- seq 行存储方向表示的有效元素数目变量是dim。

图 1 跨度（stride）示意图

对齐

硬件为了快速访问内存首地址或者跨行访问数据，要求内存地址或内存跨度必须为对齐系数的倍数。
- 数据内存首地址对齐
- 跨度对齐
输入、输出数据类型
- 块数据
  
  ot_svp_blob、ot_svp_src_blob、ot_svp_dst_blob，类型参考ot_svp_blob_type，具体的内存分配如图2～图18所示。
- 一维数据
  
  ot_svp_mem_info，表示一维数据，如图19。
BLOB内存排布类型

表 1 BLOB内存排布类型表

类型	BLOB描述
OT_SVP_BLOB_TYPE_S20Q12	多帧多通道S20Q12类型数据Planar格式存储顺序排布。此时ot_svp_blob结构体中，num表示帧数，width表示图像宽，height表示图像高，chn表示单帧图像通道数，如 OT_SVP_BLOB_TYPE_S20Q12类型ot_svp_blob（2通道2帧示意图）所示。
OT_SVP_BLOB_TYPE_U8	多帧无符号8bit多通道数据Planar格式存储顺序排布。此时ot_svp_blob结构体中，num表示帧数，width表示图像宽，height表示图像高，chn表示单帧图像通道数，如 OT_SVP_BLOB_TYPE_U8类型ot_svp_blob（3通道2帧示意图）所示。
OT_SVP_BLOB_TYPE_YVU420SP	多帧YCbCr420 SemiPlannar数据格式图像顺序排布。此时ot_svp_blob结构体中，num表示帧数，width表示图像宽，height表示图像高，chn=3，如 OT_SVP_BLOB_TYPE_YVU420SP类型ot_svp_blob（2帧YVU420SP示意图）所示。色度部分V在前，U在后。注意此时高、宽必须为偶数。
OT_SVP_BLOB_TYPE_YVU422SP	多帧YCbCr422 SemiPlannar数据格式图像顺序排布。此时ot_svp_blob结构体中，num表示帧数，width表示图像宽，height表示图像高，chn=3，如 OT_SVP_BLOB_TYPE_YVU422SP类型ot_svp_blob（2帧YVU422SP示意图）所示。色度部分V在前，U在后。注意此时宽必须为偶数。
OT_SVP_BLOB_TYPE_VEC_S20Q12	多帧S20Q12类型向量数据顺序排布。此时ot_svp_blob结构体中，num表示帧数，width表示向量数据维度，height表示单帧有多少个向量（一般height=1），chn=1，如 OT_SVP_BLOB_TYPE_VEC_S20Q12类型ot_svp_blob（2帧示意图）所示。
OT_SVP_BLOB_TYPE_SEQ_S20Q12	多段S20Q12类型序列数据排布。此时ot_svp_blob结构体中，num表示段数，dim表示序列向量数据维度，virt_addr_step是一个num长度的数组地址，数组元素表示每段序列有多少个向量，如 OT_SVP_BLOB_TYPE_SEQ_S20Q12类型ot_svp_blob (num=N帧示意图)所示。
OT_SVP_BLOB_TYPE_BBOX_S20Q12	多帧多通道S20Q12类型数据Planar格式存储顺序排布。此时ot_svp_blob结构体中，num表示帧数，width=4，height表示bbox个数，chn=1，如 OT_SVP_BLOB_TYPE_BBOX_S20Q12类型ot_svp_blob(1通道1帧示意图）所示。
OT_SVP_BLOB_TYPE_BSI_SQ32	多帧多通道32bit量化数据Planar格式存储顺序排布。此时ot_svp_blob结构体中，num表示帧数，width表示坐标最大个数，height=6，chn表述类别个数，如 OT_SVP_BLOB_TYPE_BSI_SQ32类型ot_svp_blob（2通道2帧示意图）所示。
OT_SVP_BLOB_TYPE_S12Q20	多帧多通道S12Q20类型数据Planar格式存储顺序排布。此时ot_svp_blob结构体中，num表示帧数，width表示图像宽，height表示图像高，chn表示单帧图像通道数，如 OT_SVP_BLOB_TYPE_S12Q20类型ot_svp_blob（2通道2帧示意图）所示。
OT_SVP_BLOB_TYPE_VEC_S12Q20	多帧S12Q20类型向量数据顺序排布。此时ot_svp_blob结构体中，num表示帧数，width表示向量数据维度，height表示单帧有多少个向量（一般height=1），chn=1，如 OT_SVP_BLOB_TYPE_VEC_S12Q20类型ot_svp_blob（2帧示意图）所示。
OT_SVP_BLOB_TYPE_S32	多帧多通道有符号32bit数据Planar格式存储顺序排布。此时ot_svp_blob结构体中，num表示帧数，width表示图像宽，height表示图像高，chn表示单帧图像通道数，如 OT_SVP_BLOB_TYPE_S32类型ot_svp_blob（2通道2帧示意图）所示。
OT_SVP_BLOB_TYPE_U32	多帧多通道无符号32bit数据Planar格式存储顺序排布。此时ot_svp_blob结构体中，num表示帧数，width表示图像宽，height表示图像高，chn表示单帧图像通道数，如 OT_SVP_BLOB_TYPE_U32类型ot_svp_blob（2通道2帧示意图）所示。
OT_SVP_BLOB_TYPE_FP32	多帧多通道32bit浮点数据Planar格式存储顺序排布。此时ot_svp_blob结构体中，num表示帧数，width表示图像宽，height表示图像高，chn表示单帧图像通道数，如 OT_SVP_BLOB_TYPE_FP32类型ot_svp_blob（2通道2帧示意图）所示。
OT_SVP_BLOB_TYPE_FP16	多帧多通道16bit浮点数据Planar格式存储顺序排布。此时ot_svp_blob结构体中，num表示帧数，width表示图像宽，height表示图像高，chn表示单帧图像通道数，如 OT_SVP_BLOB_TYPE_FP16类型ot_svp_blob（2通道2帧示意图）所示。
OT_SVP_BLOB_TYPE_S8	多帧多通道有符号8bit数据Planar格式存储顺序排布。此时ot_svp_blob结构体中，num表示帧数，width表示图像宽，height表示图像高，chn表示单帧图像通道数，如 OT_SVP_BLOB_TYPE_S8类型ot_svp_blob（2通道2帧示意图）所示。
OT_SVP_BLOB_TYPE_S16	多帧多通道有符号16bit数据Planar格式存储顺序排布。此时ot_svp_blob结构体中，num表示帧数，width表示图像宽，height表示图像高，chn表示单帧图像通道数，如 OT_SVP_BLOB_TYPE_S16类型ot_svp_blob（2通道2帧示意图）所示。
OT_SVP_BLOB_TYPE_U16	多帧多通道无符号8bit数据Planar格式存储顺序排布。此时ot_svp_blob结构体中，num表示帧数，width表示图像宽，height表示图像高，chn表示单帧图像通道数，如 OT_SVP_BLOB_TYPE_U16类型ot_svp_blob（2通道2帧示意图）所示。

图 2 OT_SVP_BLOB_TYPE_S20Q12类型ot_svp_blob（2通道2帧示意图）

图 3 OT_SVP_BLOB_TYPE_U8类型ot_svp_blob（3通道2帧示意图）

注：典型的RGB\HSV\LAB图像Planar格式存储。

图 4 OT_SVP_BLOB_TYPE_YVU420SP类型ot_svp_blob（2帧YVU420SP示意图）

注：这里V在前，U在后。

图 5 OT_SVP_BLOB_TYPE_YVU422SP类型ot_svp_blob（2帧YVU422SP示意图）

注：这里V在前，U在后。

图 6 OT_SVP_BLOB_TYPE_VEC_S20Q12类型ot_svp_blob（2帧示意图）

图 7 OT_SVP_BLOB_TYPE_SEQ_S20Q12类型ot_svp_blob (num=N帧示意图)

图 8 OT_SVP_BLOB_TYPE_BBOX_S20Q12类型ot_svp_blob(1通道1帧示意图)

图 9 OT_SVP_BLOB_TYPE_BSI_SQ32类型ot_svp_blob（2通道2帧示意图）

注：align32表示32字节对齐。

图 10 OT_SVP_BLOB_TYPE_S12Q20类型ot_svp_blob（2通道2帧示意图）

图 11 OT_SVP_BLOB_TYPE_VEC_S12Q20类型ot_svp_blob（2帧示意图）

图 12 OT_SVP_BLOB_TYPE_S32类型ot_svp_blob（2通道2帧示意图）

图 13 OT_SVP_BLOB_TYPE_U32类型ot_svp_blob（2通道2帧示意图）

图 14 OT_SVP_BLOB_TYPE_FP32类型ot_svp_blob（2通道2帧示意图）

图 15 OT_SVP_BLOB_TYPE_FP16类型ot_svp_blob（2通道2帧示意图）

图 16 OT_SVP_BLOB_TYPE_S8类型ot_svp_blob（2通道2帧示意图）

图 17 OT_SVP_BLOB_TYPE_S16类型ot_svp_blob（2通道2帧示意图）

图 18 OT_SVP_BLOB_TYPE_U16类型ot_svp_blob（2通道2帧示意图）

图 19 ot_svp_mem_info 类型的数据内存示意

使用示意¶

用户根据需求调用相应的算子接口创建任务，指定is_instant类型，并记录该任务返回的handle号。
根据返回的handle号，指定阻塞方式，可以查询到该任务的完成状态。

API参考¶

MAU模块提供了创建任务和查询任务的基本接口。

ss_mpi_svp_mau_matrix_mul：计算矩阵乘积。
ss_mpi_svp_mau_cos_dist：计算余弦距离。
ss_mpi_svp_mau_euclid_dist：计算欧式距离。
ss_mpi_svp_mau_manhattan_dist：计算曼哈顿距离。
ss_mpi_svp_mau_transpose：计算矩阵转置运算。
ss_mpi_svp_mau_vector_op：计算向量加减及加减绝对值运算。
ss_mpi_svp_mau_type_convert：计算矩阵数据类型FP32和FP16相互转换。
ss_mpi_svp_mau_get_sort_tmpbuf_size：获取排序运算辅助内存字节数。
ss_mpi_svp_mau_sort：计算矩阵每一行数据进行排序。
ss_mpi_svp_mau_get_fir_tmpbuf_size：获取快速图像检索辅助内存字节数。
ss_mpi_svp_mau_fir：快速图像检索。
ss_mpi_svp_mau_query：查询任务是否完成。
ss_mpi_svp_mau_add_mem_info：记录内存地址信息。
ss_mpi_svp_mau_rm_mem_info：移除内存地址信息。

ss_mpi_svp_mau_matrix_mul¶

【描述】

计算矩阵乘积。

【语法】

td_s32 ss_mpi_svp_mau_matrix_mul(ot_svp_mau_handle *handle, const ot_svp_mau_src_double_matrix *src, const ot_svp_mau_src_double_matrix *src_idx, const ot_svp_mau_ctrl *ctrl, const ot_svp_dst_blob *dst);

【参数】

参数名称	描述	输入/输出
handle	handle指针。不能为空。	输出
src	输入左右矩阵。不能为空。数据类型仅支持OT_SVP_BLOB_TYPE_FP32和OT_SVP_BLOB_TYPE_FP16。如果数据类型为OT_SVP_BLOB_TYPE_FP32，宽的取值范围：[1, 8192]，高的取值范围：[1, 1000000]，chn取值为1，num取值为1，物理地址4字节对齐，虚拟地址不使用，不做参数异常检查，stride 16字节对齐。如果数据类型为OT_SVP_BLOB_TYPE_FP16，宽的取值范围：[1, 16384]，高的取值范围：[1, 1000000]，chn取值为1，num取值为1，物理地址2字节对齐，虚拟地址不使用，不做参数异常检查，stride 16字节对齐。左右矩阵的宽必须相等。	输入
src_idx	输入左右矩阵的行索引。如果ctrl信息中has_left_idx或者has_right_idx的值为TD_TRUE时，不能为空。	输入
ctrl	输入控制信息。不能为空。	输入
dst	输出结果。不能为空。	输出

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【解决方案差异】

解决方案名称	差异
SS928V100	dst数据类型仅支持OT_SVP_BLOB_TYPE_FP32。
SS927V100	dst数据类型仅支持OT_SVP_BLOB_TYPE_FP32。

【需求】

头文件：ot_common_svp.h、ot_common_mau.h、ss_mpi_mau.h
库文件：libss_mau.a

【注意】

输入右矩阵B的数据在内存中需要按照列优先排布，所以右矩阵B和左矩阵A的宽相等，计算公式如下：

其中：

支持通过索引指定要计算的行向量，分三种情况：
- 左矩阵A通过索引指定，右矩阵不用索引，计算公式：
  
  其中：
  
  为左矩阵，为左矩阵索引(), 为左矩阵，为右矩阵，为计算结果。
- 左矩阵A不用索引，右矩阵用索引指定要计算的行向量，计算公式：
  
  其中：
  
  为左矩阵，为右矩阵，为右矩阵索引()，为计算结果。
- 左矩阵A用索引指定要计算的行向量，右矩阵B用索引指定要计算的行向量，计算公式：
  
  其中：
  
  为左矩阵，为左矩阵索引()，为右矩阵，为右矩阵索引()，为计算结果。
输入右矩阵B的数据在内存中需要按照列优先排布，左矩阵A和右矩阵B在内存中的数据排布如下：

图 1 左矩阵A内存排布

图 2 右矩阵B内存排布
用户需要确保输入左右矩阵的数据中不能含有INF、-INF或者NAN数据，并且输入数值和计算结果都在fp32数据表示有效范围内，否则会导致输出的结果数值中有INF、-INF或NAN，从而使结果数值失去意义。
ctrl->out_type仅支持OT_SVP_MAU_OUT_OP_RESULT。ctrl->has_left_idx，ctrl->has_right_idx和ctrl->is_instant值必须为TD_TRUE或TD_FALSE。
如果ctrl->has_left_idx等于TD_TRUE，src_idx->left_matrix的宽取值范围：[1, 100000]，高必须为1，chn必须为1，num必须为1，物理地址需要4字节对齐，虚拟地址不使用，不做参数异常检查，stride需要16字节对齐，src_idx->left_matrix的内存中存储的索引值必须小于src->left_matrix的高，数据类型仅支持OT_SVP_BLOB_TYPE_U32。
如果ctrl->has_right_idx等于TD_TRUE，src_idx->right_matrix的宽取值范围为[1, 100000]，高必须为1，chn必须为1，num必须为1，物理地址需要4字节对齐，虚拟地址不使用，不做参数异常检查，stride需要16字节对齐，src_idx->right_matrix的内存中存储的索引值必须小于src->right_matrix的高，数据类型仅支持OT_SVP_BLOB_TYPE_U32。
dst的chn必须等于1，num必须为1，数据类型为OT_SVP_BLOB_TYPE_FP32或OT_SVP_BLOB_TYPE_FP16，数据类型为FP32时，物理地址需要4字节对齐，数据类型为FP16时，物理地址需要2字节对齐；虚拟地址不使用，不做参数异常检查，stride需要16字节对齐;dst的宽和高要求可分为以下4种情况：
- 如果ctrl->has_left_idx等于TD_FALSE，ctrl->has_right_idx等于TD_FALSE，dst的高必须等于src->left_matrix的高，dst的宽必须等于src->right_matrix的高。
- 如果ctrl->has_left_idx等于TD_TRUE，ctrl->has_right_idx等于TD_FALSE，dst的高必须等于src_idx->left_matrix的宽，dst的宽必须等于src->right_matrix的高。
- 如果ctrl->has_left_idx等于TD_FALSE，ctrl->has_right_idx等于TD_TRUE，dst的高必须等于src->left_matrix的高，dst的宽必须等于src_idx->right_matrix的宽。
- 如果ctrl->has_left_idx等于TD_TRUE，ctrl->has_right_idx等于TD_TRUE，dst的高必须等于src_idx->left_matrix的宽，dst的宽必须等于src_idx->right_matrix的宽。

【举例】

无。

【相关主题】

无。

ss_mpi_svp_mau_cos_dist¶

【描述】

计算余弦距离。

【语法】

td_s32 ss_mpi_svp_mau_cos_dist(ot_svp_mau_handle *handle, const ot_svp_mau_src_double_matrix *src, const ot_svp_mau_src_double_matrix *src_idx, const ot_svp_mau_ctrl *ctrl, const ot_svp_mau_dist_result *dst);

【参数】

参数名称	描述	输入/输出
handle	handle指针。不能为空。	输出
src	输入左右矩阵。不能为空。数据类型仅支持OT_SVP_BLOB_TYPE_FP32和OT_SVP_BLOB_TYPE_FP16。如果数据类型为OT_SVP_BLOB_TYPE_FP32，宽的取值范围：[1, 8192]，高的取值范围：[1, 1000000]，chn为1，num取值为1，物理地址需要4字节对齐，虚拟地址不使用，不做参数异常检查，stride 需要16字节对齐。如果数据类型为OT_SVP_BLOB_TYPE_FP16，宽的取值范围：[1, 16384]，高的取值范围：[1, 1000000]，chn为1，num取值为1，物理地址需要2字节对齐，虚拟地址不使用，不做参数异常检查，stride 需要16字节对齐。左右矩阵的宽必须相等。左右矩阵的行向量必须做单位化，即行向量模为1。	输入
src_idx	输入左右矩阵的行索引。当ctrl信息中has_left_idx或者has_right_idx为TD_TRUE时，不能为空。	输入
ctrl	输入控制信息。不能为空。	输入
dst	输出结果。不能为空。	输出

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【解决方案差异】

解决方案名称	差异
SS928V100	dst->op_result和dst->top_n数据类型仅支持OT_SVP_BLOB_TYPE_FP32。
SS927V100	dst->op_result和dst->top_n数据类型仅支持OT_SVP_BLOB_TYPE_FP32。

【需求】

头文件：ot_common_svp.h、ot_common_mau.h、ss_mpi_mau.h
库文件：libss_mau.a

【注意】

用户需要对输入的左右矩阵中的行向量做单位化处理，否则可能会计算结果不正确。
支持多向量求余弦距离，Height表示向量个数，依次获取左矩阵A的行向量与右矩阵B中每个行向量进行计算，计算公式：

其中：

为左矩阵，为右矩阵，为结果矩阵，为Top_n矩阵，每一行中的数值为矩阵中对应行中从大到小排序后的前Top t个，为Top_n索引矩阵，的值是中第i个行向量与中第个行向量的余弦距离。
支持通过索引指定要计算的行向量，分三种情况：
- 左矩阵A通过索引指定要计算的行向量，右矩阵不用索引，计算公式：
  
  其中：
  
  为左矩阵，为左矩阵索引()，为右矩阵，为结果矩阵，为Top_n矩阵，每一行中的数值为矩阵中对应行中从大到小排序后的前Top t个值，为Top_n索引矩阵，的值是中第个行向量与中第个行向量的余弦距离。
- 左矩阵A不用索引，右矩阵用索引指定要计算的行向量，计算公式：
  
  其中：
  
  为左矩阵，为右矩阵，为右矩阵索引()，为结果矩阵，为Top_n矩阵，每一行中的数值为矩阵中对应行中从大到小排序后的前Top t个值，为Top_n索引矩阵，的值是中第i个行向量与中第个行向量的余弦距离。
- 左矩阵A用索引指定要计算的行向，右矩阵B用索引指定要计算的行向量，计算公式：
  
  其中：
  
  为左矩阵，为左矩阵索引()，为右矩阵，为右矩阵索引()，为结果矩阵，为Top_n矩阵，每一行中的数值为矩阵中对应行中从大到小排序后的前Top t个值，为Top_n索引矩阵，的值是中第个行向量与中第个行向量的余弦距离。
左矩阵A和右矩阵B在内存中的数据排布如下：

图 1 左矩阵A内存排布

图 2 右矩阵B内存排布
用户需要确保输入左右矩阵的数据中不能含有INF、-INF或者NAN数据，并且输入数值和计算结果都在fp32数据表示有效范围内，否则会导致输出的结果数值中有INF、-INF或NAN，从而使结果数值失去意义。
ctrl->out_type可支持OT_SVP_MAU_OUT_OP_RESULT，OT_SVP_MAU_OUT_TOP_N和OT_SVP_MAU_OUT_BOTH。ctrl->has_left_idx，ctrl->has_right_idx和ctrl->is_instant值必须为TD_TRUE或TD_FALSE。
如果ctrl->has_left_idx等于TD_TRUE，src_idx->left_matrix的宽取值范围：[1, 100000]，高必须为1，chn必须为1，num必须为1，物理地址需要4字节对齐，虚拟地址不使用，不做参数异常检查，stride 需要16字节对齐，内存中存储的索引必须小于src->left_matrix的高，数据类型仅支持OT_SVP_BLOB_TYPE_U32。
如果ctrl->has_right_idx等于TD_TRUE，src_idx->right_matrix的宽取值范围为[1, 100000]，高必须为1，chn必须为1，num必须为1，物理地址需要4字节对齐，虚拟地址不使用，不做参数异常检查，stride 需要16字节对齐，内存中存储的索引必须小于src->right_matrix的高，数据类型仅支持OT_SVP_BLOB_TYPE_U32。
如果ctrl->out_type为OT_SVP_MAU_OUT_OP_RESULT或者OT_SVP_MAU_OUT_BOTH，dst-> op_result的chn必须等于1，num必须为1，数据类型为OT_SVP_BLOB_TYPE_FP32或OT_SVP_BLOB_TYPE_FP16，数据类型为FP32时，物理地址需要4字节对齐，数据类型为FP16时，物理地址需要2字节对齐；虚拟地址不使用，不做参数异常检查，stride需要16字节对齐;dst-> op_result的宽和高要求可分为以下4种情况：
- 如果ctrl->has_left_idx等于TD_FALSE，ctrl->has_right_idx等于TD_FALSE，dst-> op_result的高必须等于src->left_matrix的高，dst-> op_result的宽必须等于src->right_matrix的高。
- 如果ctrl->has_left_idx等于TD_TRUE，ctrl->has_right_idx等于TD_FALSE，dst-> op_result的高必须等于src_idx->left_matrix的宽，dst-> op_result的宽必须等于src->right_matrix的高。
- 如果ctrl->has_left_idx等于TD_FALSE，ctrl->has_right_idx等于TD_TRUE，dst-> op_result的高必须等于src->left_matrix的高，dst-> op_result的宽必须等于src_idx->right_matrix的宽。
- 如果ctrl->has_left_idx等于TD_TRUE，ctrl->has_right_idx等于TD_TRUE，dst-> op_result的高必须等于src_idx->left_matrix的宽，dst-> op_result的宽必须等于src_idx->right_matrix的宽。
如果ctrl->out_type为OT_SVP_MAU_OUT_TOP_N或者OT_SVP_MAU_OUT_BOTH，dst-> top_n的chn必须等于1，num必须为1，stride需要16字节对齐，数据类型为OT_SVP_BLOB_TYPE_FP32或OT_SVP_BLOB_TYPE_FP16，数据类型为FP32时，物理地址需要4字节对齐，数据类型为FP16时，物理地址需要2字节对齐；虚拟地址不使用，不做参数异常检查；dst-> top_n的宽表示输出从大到小排序后的前Top_n个余弦距离，最大只能输出Top 32。具体宽和高要求可分为以下4种情况：
- 如果ctrl->has_left_idx等于TD_FALSE，ctrl->has_right_idx等于TD_FALSE，dst-> top_n的高必须等于src->left_matrix的高，dst-> top_n的宽取值范围为[1，min(src->right_matrix.shape.whc.height，32)]。
- 如果ctrl->has_left_idx等于TD_TRUE，ctrl->has_right_idx等于TD_FALSE，dst-> top_n的高必须等于src_idx->left_matrix的宽，dst-> top_n的宽取值范围为[1，min(src->right_matrix.shape.whc.height，32)]。
- 如果ctrl->has_left_idx等于TD_FALSE，ctrl->has_right_idx等于TD_TRUE，dst-> top_n的高必须等于src->left_matrix的高，dst-> top_n的宽取值范围为[1，min(src_idx->right_matrix.shape.whc.width，32)]。
- 如果ctrl->has_left_idx等于TD_TRUE，ctrl->has_right_idx等于TD_TRUE，dst-> top_n的高必须等于src_idx->left_matrix的宽，dst-> top_n的宽取值范围为[1，min(src_idx->right_matrix.shape.whc.width，32)]。
如果ctrl->out_type为OT_SVP_MAU_OUT_TOP_N或者OT_SVP_MAU_OUT_BOTH，dst-> top_n_idx的chn必须等于1，num必须为1，stride需要16字节对齐，物理地址需要4字节对齐，虚拟地址不使用，不做参数异常检查，数据类型必须为OT_SVP_BLOB_TYPE_U32，宽高必须与dst-> top_n的宽高相等。

【举例】

无。

【相关主题】

无。

ss_mpi_svp_mau_euclid_dist¶

【描述】

计算欧式距离。

【语法】

td_s32 ss_mpi_svp_mau_euclid_dist(ot_svp_mau_handle *handle, const ot_svp_mau_src_double_matrix *src,  const ot_svp_mau_src_double_matrix *src_idx, const ot_svp_mau_ctrl *ctrl, const ot_svp_mau_dist_result *dst);

【参数】

参数名称	描述	输入/输出
handle	handle指针。不能为空。	输出
src	输入左右矩阵。不能为空。数据类型仅支持OT_SVP_BLOB_TYPE_FP32和OT_SVP_BLOB_TYPE_FP16。如果数据类型为OT_SVP_BLOB_TYPE_FP32，宽的取值范围：[1, 8192]，高的取值范围：[1, 1000000]，chn为1，num取值为1，物理地址需要4字节对齐，虚拟地址不使用，不做参数异常检查，stride 需要16字节对齐。如果数据类型为OT_SVP_BLOB_TYPE_FP16，宽的取值范围：[1, 16384]，高的取值范围：[1, 1000000]，chn为1，num取值为1，物理地址需要2字节对齐，虚拟地址不使用，不做参数异常检查，stride 需要16 字节对齐。左右矩阵的宽必须相等。	输入
src_idx	输入左右矩阵的行索引。当ctrl信息中has_left_idx或者has_right_idx为TD_TRUE时，不能为空。	输入
ctrl	输入控制信息。不能为空。	输入
dst	输出结果。不能为空。	输出

【解决方案差异】

解决方案名称	差异
SS928V100	dst->op_result和dst->top_n数据类型仅支持OT_SVP_BLOB_TYPE_FP32。
SS927V100	dst->op_result和dst->top_n数据类型仅支持OT_SVP_BLOB_TYPE_FP32。

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_svp.h、ot_common_mau.h、ss_mpi_mau.h
库文件：libss_mau.a

【注意】

支持多向量求欧氏距离，Height表示向量个数，依次获取左矩阵A的行向量与右矩阵中每个行向量进行计算，计算公式：

其中：

为左矩阵，为右矩阵，为结果矩阵，为Top_n矩阵，每一行中的数值为矩阵中对应行中从小到大排序后的前Top t个，为Top_n索引矩阵，的值是中第i个行向量与中第个行向量的欧式距离。
支持通过索引指定要计算的行向量，分三种情况：
- 左矩阵A通过索引指定要计算的行向量，右矩阵不用索引，计算公式：
  
  其中：
  
  为左矩阵，为左矩阵索引()，为右矩阵，为结果矩阵，为Top_n矩阵，每一行中的数值为矩阵中对应行中从小到大排序后的前Top t个值，为Top_n索引矩阵，的值是中第个行向量与中第个行向量的欧式距离。
- 左矩阵A不用索引，右矩阵用索引指定要计算的行向量，计算公式：
  
  其中：
  
  为左矩阵，为右矩阵，为右矩阵索引()，为结果矩阵，为Top_n矩阵，每一行中的数值为矩阵中对应行中从小到大排序后的前Top t个值，为Top_n索引矩阵，的值是中第i个行向量与中第个行向量的欧式距离。
- 左矩阵A用索引指定要计算的行向，右矩阵B用索引指定要计算的行向量，计算公式：
  
  其中：
  
  为左矩阵，为左矩阵索引()，为右矩阵，为右矩阵索引()，为结果矩阵，为Top_n矩阵，每一行中的数值为矩阵中对应行中从小到大排序后的前Top t个值，为Top_n索引矩阵，的值是中第个行向量与中第个行向量的欧式距离。
左矩阵A和右矩阵B在内存中的数据排布如下：

图 1 左矩阵A内存排布

图 2 右矩阵B内存排布
用户需要确保输入左右矩阵的数据中不能含有INF、-INF或者NAN数据，并且输入数值和计算结果都在fp32数据表示有效范围内，否则会导致输出的结果中数值为INF、-INF或NAN，从而使结果数值失去意义。
ctrl->out_type可支持OT_SVP_MAU_OUT_OP_RESULT，OT_SVP_MAU_OUT_TOP_N和OT_SVP_MAU_OUT_BOTH。ctrl->has_left_idx，ctrl->has_right_idx和ctrl->is_instant值必须为TD_TRUE或TD_FALSE。
如果ctrl->has_left_idx等于TD_TRUE，src_idx->left_matrix的宽取值范围：[1, 100000]，高必须为1，chn必须为1，num必须为1，物理地址需要4字节对齐，虚拟地址不使用，不做参数异常检查，stride 需要16字节对齐，内存中存储的索引必须小于src->left_matrix的高，数据类型仅支持OT_SVP_BLOB_TYPE_U32。
如果ctrl->has_right_idx等于TD_TRUE，src_idx->right_matrix的宽取值范围为[1, 100000]，高必须为1，chn必须为1，num必须为1，物理地址需要4字节对齐，虚拟地址不使用，不做参数异常检查，stride 需要16字节对齐，内存中存储的索引必须小于src->right_matrix的高，数据类型仅支持OT_SVP_BLOB_TYPE_U32。
如果ctrl->out_type为OT_SVP_MAU_OUT_OP_RESULT或者OT_SVP_MAU_OUT_BOTH，dst-> op_result的chn必须等于1，num必须为1，数据类型为OT_SVP_BLOB_TYPE_FP32或OT_SVP_BLOB_TYPE_FP16，数据类型为FP32时，物理地址需要4字节对齐，数据类型为FP16时，物理地址需要2字节对齐；虚拟地址不使用，不做参数异常检查，stride 需要16字节对齐;dst-> op_result的宽和高要求可分为以下4种情况：
- 如果ctrl->has_left_idx等于TD_FALSE，ctrl->has_right_idx等于TD_FALSE，dst-> op_result的高必须等于src->left_matrix的高，dst-> op_result的宽必须等于src->right_matrix的高。
- 如果ctrl->has_left_idx等于TD_TRUE，ctrl->has_right_idx等于TD_FALSE，dst-> op_result的高必须等于src_idx->left_matrix的宽，dst-> op_result的宽必须等于src->right_matrix的高。
- 如果ctrl->has_left_idx等于TD_FALSE，ctrl->has_right_idx等于TD_TRUE，dst-> op_result的高必须等于src->left_matrix的高，dst-> op_result的宽必须等于src_idx->right_matrix的宽。
- 如果ctrl->has_left_idx等于TD_TRUE，ctrl->has_right_idx等于TD_TRUE，dst-> op_result的高必须等于src_idx->left_matrix的宽，dst-> op_result的宽必须等于src_idx->right_matrix的宽。
如果ctrl->out_type为OT_SVP_MAU_OUT_TOP_N或者OT_SVP_MAU_OUT_BOTH，dst-> top_n的chn必须等于1，num必须为1，数据类型为OT_SVP_BLOB_TYPE_FP32或OT_SVP_BLOB_TYPE_FP16，数据类型为FP32时，物理地址需要4字节对齐，数据类型为FP16时，物理地址需要2字节对齐；虚拟地址不使用，不做参数异常检查，stride需要16字节对齐；dst-> top_n的宽表示输出从小到大排序后的前Top_n个欧式距离，最大只能输出Top 32。具体宽和高要求可分为以下4种情况：
- 如果ctrl->has_left_idx等于TD_FALSE，ctrl->has_right_idx等于TD_FALSE，dst-> top_n的高必须等于src->left_matrix的高，dst-> top_n的宽取值范围为[1，min(src->right_matrix.shape.whc.height，32)]。
- 如果ctrl->has_left_idx等于TD_TRUE，ctrl->has_right_idx等于TD_FALSE，dst-> top_n的高必须等于src_idx->left_matrix的宽，dst-> top_n的宽取值范围为[1，min(src->right_matrix.shape.whc.height，32)]。
- 如果ctrl->has_left_idx等于TD_FALSE，ctrl->has_right_idx等于TD_TRUE，dst-> top_n的高必须等于src->left_matrix的高，dst-> top_n的宽取值范围为[1，min(src_idx->right_matrix.shape.whc.width，32)]。
- 如果ctrl->has_left_idx等于TD_TRUE，ctrl->has_right_idx等于TD_TRUE，dst-> top_n的高必须等于src_idx->left_matrix的宽，dst-> top_n的宽取值范围为[1，min(src_idx->right_matrix.shape.whc.width，32)]。
如果ctrl->out_type为OT_SVP_MAU_OUT_TOP_N或者OT_SVP_MAU_OUT_BOTH，dst-> top_n_idx的chn必须等于1，num必须为1，stride需要16字节对齐，物理地址需要4字节对齐，虚拟地址不使用，不做参数异常检查，数据类型必须为OT_SVP_BLOB_TYPE_U32，宽高必须与dst-> top_n的宽高相等。

【举例】

无。

【相关主题】

无。

ss_mpi_svp_mau_manhattan_dist¶

【描述】

计算曼哈顿距离。

【语法】

td_s32 ss_mpi_svp_mau_manhattan_dist(ot_svp_mau_handle *handle, const ot_svp_mau_src_double_matrix *src,  const ot_svp_mau_src_double_matrix *src_idx, const ot_svp_mau_ctrl *ctrl, const ot_svp_mau_dist_result *dst);

【参数】

参数名称	描述	输入/输出
handle	handle指针。不能为空。	输出
src	输入左右矩阵。不能为空。数据类型仅支持OT_SVP_BLOB_TYPE_FP32和OT_SVP_BLOB_TYPE_FP16。如果数据类型为OT_SVP_BLOB_TYPE_FP32，宽的取值范围：[1, 8192]，高的取值范围：[1, 1000000]，chn为1，num取值为1，物理地址需要4字节对齐，虚拟地址不使用，不做参数异常检查，stride 需要16字节对齐。如果数据类型为OT_SVP_BLOB_TYPE_FP16，宽的取值范围：[1, 16384]，高的取值范围：[1, 1000000]，chn为1，num取值为1，物理地址需要2字节对齐，虚拟地址不使用，不做参数异常检查，stride 需要16字节对齐。左右矩阵的宽必须相等。	输入
src_idx	输入左右矩阵的行索引。当ctrl信息中has_left_idx或者has_right_idx为TD_TRUE时，不能为空。	输入
ctrl	输入控制信息。不能为空。	输入
dst	输出结果。不能为空。	输出

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【解决方案差异】

解决方案名称	差异
SS928V100	不支持
SS927V100	不支持

【需求】

头文件：ot_common_svp.h、ot_common_mau.h、ss_mpi_mau.h
库文件：libss_mau.a

【注意】

支持多向量求曼哈顿距离，Height表示向量个数，依次获取左矩阵A的行向量与右矩阵中每个行向量进行计算，计算公式：

其中：

为左矩阵，为右矩阵，为结果矩阵，为Top_n矩阵，每一行中的数值为矩阵中对应行中从小到大排序后的前Top t个，为Top_n索引矩阵，的值是中第i个行向量与中第个行向量的曼哈顿距离。
支持通过索引指定要计算的行向量，分三种情况：
- 左矩阵A通过索引指定要计算的行向量，右矩阵不用索引，计算公式：
  
  其中：
  
  为左矩阵，为左矩阵索引()，为右矩阵，为结果矩阵，为Top_n矩阵，每一行中的数值为矩阵中对应行中从小到大排序后的前Top t个值，为Top_n索引矩阵，的值是中第个行向量与中第中第个行向量的曼哈顿距离。
- 左矩阵A不用索引，右矩阵用索引指定要计算的行向量，计算公式：
  
  其中：
  
  为左矩阵，为右矩阵，为右矩阵索引()，为结果矩阵，为Top_n矩阵，每一行中的数值为矩阵中对应行中从小到大排序后的前Top t个值，为Top_n索引矩阵，的值是中第i个行向量与中第个行向量的曼哈顿距离。
- 左矩阵A用索引指定要计算的行向，右矩阵B用索引指定要计算的行向量，计算公式：
  
  其中：
  
  为左矩阵，为左矩阵索引()，为右矩阵，为右矩阵索引()，为结果矩阵，为Top_n矩阵，每一行中的数值为矩阵中对应行中从小到大排序后的前Top t个值，为Top_n索引矩阵，的值是中第个行向量与中第个行向量的曼哈顿距离。
左矩阵A和右矩阵B在内存中的数据排布如下：

图 1 左矩阵A内存排布

图 2 右矩阵B内存排布
用户需要确保输入左右矩阵的数据中不能含有INF、-INF或者NAN数据，并且输入数值和计算结果都在fp32数据表示有效范围内，否则会导致输出的结果中数值为INF、-INF或NAN，从而使结果数值失去意义。
ctrl->out_type可支持OT_SVP_MAU_OUT_OP_RESULT，OT_SVP_MAU_OUT_TOP_N和OT_SVP_MAU_OUT_BOTH。ctrl->has_left_idx，ctrl->has_right_idx和ctrl->is_instant值必须为TD_TRUE或TD_FALSE。
如果ctrl->has_left_idx等于TD_TRUE，src_idx->left_matrix的宽取值范围[1, 100000]，高必须为1，chn必须为1，num必须为1，物理地址需要4字节对齐，虚拟地址不使用，不做参数异常检查，stride需要16字节对齐，内存中存储的索引必须小于src->left_matrix的高，数据类型仅支持OT_SVP_BLOB_TYPE_U32。
如果ctrl->has_right_idx等于TD_TRUE，src_idx->right_matrix的宽取值范围为[1, 100000]，高必须为1，chn必须为1，num必须为1，物理地址需要4字节对齐，虚拟地址不使用，不做参数异常检查，stride 需要16字节对齐，内存中存储的索引必须小于src->right_matrix的高，数据类型仅支持OT_SVP_BLOB_TYPE_U32。
如果ctrl->out_type为OT_SVP_MAU_OUT_OP_RESULT或者OT_SVP_MAU_OUT_BOTH，dst-> op_result的chn必须等于1，num必须为1，数据类型为OT_SVP_BLOB_TYPE_FP32或OT_SVP_BLOB_TYPE_FP16，当ctrl->out_type为OT_SVP_MAU_OUT_BOTH时，dst->top_n和dst-> op_result数据类型必须一致；数据类型为FP32时，物理地址需要4字节对齐，数据类型为FP16时，物理地址需要2字节对齐；虚拟地址不使用，不做参数异常检查，stride 需要16字节对齐，dst-> op_result的宽和高要求可分为以下4种情况：
- 如果ctrl->has_left_idx等于TD_FALSE，ctrl->has_right_idx等于TD_FALSE，dst-> op_result的高必须等于src->left_matrix的高，dst-> op_result的宽必须等于src->right_matrix的高。
- 如果ctrl->has_left_idx等于TD_TRUE，ctrl->has_right_idx等于TD_FALSE，dst-> op_result的高必须等于src_idx->left_matrix的宽，dst-> op_result的宽必须等于src->right_matrix的高。
- 如果ctrl->has_left_idx等于TD_FALSE，ctrl->has_right_idx等于TD_TRUE，dst-> op_result的高必须等于src->left_matrix的高，dst-> op_result的宽必须等于src_idx->right_matrix的宽。
- 如果ctrl->has_left_idx等于TD_TRUE，ctrl->has_right_idx等于TD_TRUE，dst-> op_result的高必须等于src_idx->left_matrix的宽，dst-> op_result的宽必须等于src_idx->right_matrix的宽。
如果ctrl->out_type为OT_SVP_MAU_OUT_TOP_N或者OT_SVP_MAU_OUT_BOTH，dst-> top_n的chn必须等于1，num必须为1；数据类型为OT_SVP_BLOB_TYPE_FP32或OT_SVP_BLOB_TYPE_FP32，当ctrl->out_type为OT_SVP_MAU_OUT_BOTH时，dst->top_n和dst-> op_result数据类型必须一致；数据类型为FP32时，物理地址需要4字节对齐，数据类型为FP16时，物理地址需要2字节对齐；虚拟地址不使用，不做参数异常检查，stride需要16字节对齐；dst-> top_n的宽表示输出从小到大排序后的前Top_n个欧式距离，最大只能输出Top 32。具体宽和高要求可分为以下4种情况：
- 如果ctrl->has_left_idx等于TD_FALSE，ctrl->has_right_idx等于TD_FALSE，dst-> top_n的高必须等于src->left_matrix的高，dst-> top_n的宽取值范围为[1，min(src->right_matrix.shape.whc.height，32)]。
- 如果ctrl->has_left_idx等于TD_TRUE，ctrl->has_right_idx等于TD_FALSE，dst-> top_n的高必须等于src_idx->left_matrix的宽，dst-> top_n的宽取值范围为[1，min(src->right_matrix.shape.whc.height，32)]。
- 如果ctrl->has_left_idx等于TD_FALSE，ctrl->has_right_idx等于TD_TRUE，dst-> top_n的高必须等于src->left_matrix的高，dst-> top_n的宽取值范围为[1，min(src_idx->right_matrix.shape.whc.width，32)]。
- 如果ctrl->has_left_idx等于TD_TRUE，ctrl->has_right_idx等于TD_TRUE，dst-> top_n的高必须等于src_idx->left_matrix的宽，dst-> top_n的宽取值范围为[1，min(src_idx->right_matrix.shape.whc.width，32)]。
如果ctrl->out_type为OT_SVP_MAU_OUT_TOP_N或者OT_SVP_MAU_OUT_BOTH，dst-> top_n_idx的chn必须等于1，num必须为1，stride需要16字节对齐，物理地址需要4字节对齐，虚拟地址不使用，不做参数异常检查，数据类型必须为OT_SVP_BLOB_TYPE_U32，宽高必须与dst-> top_n的宽高相等。

【举例】

无。

【相关主题】

无。

ss_mpi_svp_mau_transpose¶

【描述】

计算矩阵转置运算。

【语法】

td_s32 ss_mpi_svp_mau_transpose(ot_svp_mau_handle *handle, const ot_svp_blob *src, const ot_svp_blob *src_idx, const ot_svp_mau_transpose_ctrl *ctrl, const ot_svp_blob *dst);

【参数】

参数名称	描述	输入/输出
handle	handle指针。不能为空。	输出
src	输入矩阵。不能为空。数据类型支持OT_SVP_BLOB_TYPE_FP32，OT_SVP_BLOB_TYPE_FP16, OT_SVP_BLOB_TYPE_U32, OT_SVP_BLOB_TYPE_S32, OT_SVP_BLOB_TYPE_U16, OT_SVP_BLOB_TYPE_S16, OT_SVP_BLOB_TYPE_U8, OT_SVP_BLOB_TYPE_S8。宽的取值范围：[1, 100000]，高的取值范围：[1, 100000]，chn取值为1，num取值为1，虚拟地址不使用，不做参数异常检查，stride 16字节对齐,。物理地址依据数据类对齐。FP32，U32，S32时，4字节对齐；FP16，U16，S16时，2字节对齐；U8，S8时，1字节对齐。	输入
src_idx	输入矩阵的行索引。如果ctrl信息中has_ idx值为TD_TRUE时，不能为空。	输入
ctrl	输入控制信息。不能为空。	输入
dst	输出结果。数据类型与输入矩阵数据类型一致。不能为空。	输出

注：FP32，U32，S32，FP16，U16，S16时，2字节对齐；U8，S8均为ot_svp_blob_type成员的缩写，后续其他的成员在表述中也用相同的规则简写

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【解决方案差异】

解决方案名称	差异
SS928V100	不支持
SS927V100	不支持

【需求】

头文件：ot_common_svp.h、ot_common_mau.h、ss_mpi_mau.h
库文件：libss_mau.a

【注意】

计算公式如下：

其中：

支持通过索引指定要计算的行向量：
- 矩阵A通过索引指定，计算公式：
  
  其中：
  
  为输入矩阵，为左矩阵索引()，为计算结果。
输入矩阵A在内存中的数据排布如下：

图 1 矩阵A内存排布

用户需要确保输入左右矩阵的数据中不能含有INF、-INF或者NAN数据，并且输入数值和计算结果都在fp32数据表示有效范围内，否则会导致输出的结果数值中有INF、-INF或NAN，从而使结果数值失去意义。
ctrl->has_idx和ctrl->is_instant值必须为TD_TRUE或TD_FALSE。
如果ctrl->has_idx等于TD_TRUE，src_idx的宽取值范围[1, 100000]，高必须为1，chn必须为1，num必须为1，物理地址需要4字节对齐，虚拟地址不使用，不做参数异常检查，stride需要16字节对齐，src_idx的内存中存储的索引值必须小于src的高，数据类型仅支持OT_SVP_BLOB_TYPE_U32。
dst的chn必须等于1，num必须为1；物理地址按数据类型对齐，FP32，U32，S32时，4字节对齐；FP16，U16，S16时，2字节对齐；U8，S8时，1字节对齐，虚拟地址不使用，不做参数异常检查，stride需要16字节对齐，数据类型必须与输入矩阵类型一致，dst的宽和高要求可分为以下2种情况：
- 如果ctrl->has_idx等于TD_FALSE，dst的高必须等于src的宽，dst的宽必须等于src的高。
- 如果ctrl->has_idx等于TD_TRUE，dst的高必须等于src的宽，dst的宽必须等于src_idx的宽。

【举例】

无。

【相关主题】

无。

ss_mpi_svp_mau_vector_op¶

【描述】

计算向量加减及加减绝对值运算。

【语法】

td_s32 ss_mpi_svp_mau_vector_op(ot_svp_mau_handle *handle, const ot_svp_mau_src_double_matrix *src, const ot_svp_mau_src_double_matrix *src_idx, const ot_svp_mau_vector_op_ctrl *ctrl, const ot_svp_blob *dst);

【参数】

参数名称	描述	输入/输出
handle	handle指针。不能为空。	输出
src	输入左右矩阵。不能为空。数据类型仅支持OT_SVP_BLOB_TYPE_FP32和OT_SVP_BLOB_TYPE_FP16。如果数据类型为OT_SVP_BLOB_TYPE_FP32，宽的取值范围[1, 8192]，高的取值范围[1, 1000000]，chn为1，num取值为1，物理地址需要4字节对齐，虚拟地址不使用，不做参数异常检查，stride 需要16字节对齐。如果数据类型为OT_SVP_BLOB_TYPE_FP16，宽的取值范围：[1, 16384]，高的取值范围：[1, 1000000]，chn为1，num取值为1，物理地址需要2字节对齐，虚拟地址不使用，不做参数异常检查，stride 需要16字节对齐。左右矩阵的宽必须相等。	输入
src_idx	输入左右矩阵的行索引。当ctrl信息中has_left_idx或者has_right_idx为TD_TRUE时，不能为空。	输入
ctrl	输入控制信息。不能为空。	输入
dst	输出结果。不能为空。	输出

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【解决方案差异】

解决方案名称	差异
SS928V100	不支持
SS927V100	不支持

【需求】

头文件：ot_common_svp.h、ot_common_mau.h、ss_mpi_mau.h
库文件：libss_mau.a

【注意】

支持多向量加减运算，Height表示向量个数，依次获取左矩阵A的行向量与右矩阵B中每个行向量进行计算，所以左矩阵A和右矩阵B的宽必须相等，计算公式：

其中：

向量相减运算：

向量相减的绝对值运算：

向量相加运算：

向量相加的绝对值运算：

为左矩阵，为右矩阵，为结果矩阵。
支持通过索引指定要计算的行向量，分三种情况：
- 左矩阵A通过索引指定要计算的行向量，右矩阵不用索引，计算公式：
  
  其中：
向量相减运算：

向量相减的绝对值运算：

向量相加运算：

向量相加的绝对值运算：

为左矩阵，为左矩阵索引()，为右矩阵，为结果矩阵。
- 左矩阵A不用索引，右矩阵用索引指定要计算的行向量，计算公式：
  
  其中：
向量相减运算：

向量相减的绝对值运算：

向量相加运算：

向量相加的绝对值运算：

为左矩阵，为右矩阵，为右矩阵索引()，为结果矩阵。
- 左矩阵A用索引指定要计算的行向，右矩阵B用索引指定要计算的行向量，计算公式：
  
  其中：
向量相减运算：

向量相减的绝对值运算：

向量相加运算：

向量相加的绝对值运算：

为左矩阵，为左矩阵索引()，为右矩阵，为右矩阵索引()，为结果矩阵。
左矩阵A和右矩阵B在内存中的数据排布如下：

图 1 左矩阵A内存排布

图 2 右矩阵B内存排布
用户需要确保输入左右矩阵的数据中不能含有INF、-INF或者NAN数据，并且输入数值和计算结果都在fp32数据表示有效范围内，否则会导致输出的结果数值中有INF、-INF或NAN，从而使结果数值失去意义。
ctrl->has_left_idx，ctrl->has_right_idx和ctrl->is_instant值必须为TD_TRUE或TD_FALSE。
如果ctrl->has_left_idx等于TD_TRUE，src_idx->left_matrix的宽取值范围[1, 100000]，高必须为1，chn必须为1，num必须为1，物理地址需要4字节对齐，虚拟地址不使用，不做参数异常检查，stride 需要16字节对齐，内存中存储的索引必须小于src->left_matrix的高，数据类型仅支持OT_SVP_BLOB_TYPE_U32。
如果ctrl->has_right_idx等于TD_TRUE，src_idx->right_matrix的宽取值范围为[1, 100000]，高必须为1，chn必须为1，num必须为1，物理地址需要4字节对齐，虚拟地址不使用，不做参数异常检查，stride 需要16字节对齐，内存中存储的索引必须小于src->right_matrix的高，数据类型仅支持OT_SVP_BLOB_TYPE_U32。
dst的chn必须等于1，宽等于左右矩阵的宽；数据类型为OT_SVP_BLOB_TYPE_FP32或OT_SVP_BLOB_TYPE_FP16；数据类型为FP32时，物理地址需要4字节对齐，数据类型为FP16时，物理地址需要2字节对齐；虚拟地址不使用，不做参数异常检查，stride需要16字节对齐，dst的高和num要求可分为以下4种情况：
- 如果ctrl->has_left_idx等于TD_FALSE，ctrl->has_right_idx等于TD_FALSE，dst的高必须等于src->right_matrix的高，dst的num必须等于src->left_matrix的高。
- 如果ctrl->has_left_idx等于TD_TRUE，ctrl->has_right_idx等于TD_FALSE，dst的高必须等于src>right_matrix的高，dst的num必须等于src_idx->left_matrix的宽。
- 如果ctrl->has_left_idx等于TD_FALSE，ctrl->has_right_idx等于TD_TRUE，dst的高必须等于src_idx->right_matrix的宽，dst的num必须等于src ->left_matrix的高。
- 如果ctrl->has_left_idx等于TD_TRUE，ctrl->has_right_idx等于TD_TRUE，dst的高必须等于src_idx->right_matrix的宽，dst的num必须等于src_idx->left_matrix的宽。

【举例】

无。

【相关主题】

无。

ss_mpi_svp_mau_type_convert¶

【描述】

计算矩阵数据类型FP32和FP16相互转换。

【语法】

td_s32 ss_mpi_svp_mau_type_convert(ot_svp_mau_handle *handle, const ot_svp_blob *src, const ot_svp_blob *src_idx, const ot_svp_mau_type_convert_ctrl *ctrl, const ot_svp_blob *dst);

【参数】

参数名称	描述	输入/输出
handle	handle指针。不能为空。	输出
src	输入矩阵。不能为空。数据类型仅支持OT_SVP_BLOB_TYPE_FP32和OT_SVP_BLOB_TYPE_FP16。如果数据类型为OT_SVP_BLOB_TYPE_FP32，宽的取值范围：[1, 8192]，高的取值范围：[1, 1000000]，chn取值为1，num取值为1，物理地址4字节对齐，虚拟地址不使用，不做参数异常检查，stride 16字节对齐，ctrl->mode必须为OT_SVP_MAU_TYPE_CONVERT_MODE_FP32_TO_FP16。如果数据类型为OT_SVP_BLOB_TYPE_FP16，宽的取值范围：[1, 16384]，高的取值范围：[1, 1000000]，chn取值为1，num取值为1，物理地址2字节对齐，虚拟地址不使用，不做参数异常检查，stride 16字节对齐，ctrl->mode必须为OT_SVP_MAU_TYPE_CONVERT_MODE_FP16_TO_FP32。	输入
src_idx	输入矩阵的行索引。如果ctrl信息中has_idx的值为TD_TRUE时，不能为空。	输入
ctrl	输入控制信息。不能为空。	输入
dst	输出结果。当输入矩阵数据类型为OT_SVP_BLOB_TYPE_FP32，其数据类型必须为OT_SVP_BLOB_TYPE_FP16；当输入矩阵数据类型为OT_SVP_BLOB_TYPE_FP16，其数据类型必须为OT_SVP_BLOB_TYPE_FP32 不能为空。	输出

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【解决方案差异】

解决方案名称	差异
SS928V100	不支持
SS927V100	不支持

【需求】

头文件：ot_common_svp.h、ot_common_mau.h、ss_mpi_mau.h
库文件：libss_mau.a

【注意】

输入矩阵内存中的数据排布如下：

图 1 矩阵内存排布
用户需要确保输入左右矩阵的数据中不能含有INF、-INF或者NAN数据，并且输入数值和计算结果都在fp32数据表示有效范围内，否则会导致输出的结果数值中有INF、-INF或NAN，从而使结果数值失去意义。
ctrl->has_idx，和ctrl->is_instant值必须为TD_TRUE或TD_FALSE。
如果ctrl->has_ idx等于TD_TRUE，src_idx的宽取值范围[1, 100000]，高必须为1，chn必须为1，num必须为1，物理地址需要4字节对齐，虚拟地址不使用，不做参数异常检查，stride需要16字节对齐，src_idx的内存中存储的索引值必须小于src的高，数据类型仅支持OT_SVP_BLOB_TYPE_U32。
dst的chn必须等于1，num必须为1，宽必须等于src的宽，数据类型为OT_SVP_BLOB_TYPE_FP32或OT_SVP_BLOB_TYPE_FP32；数据类型为FP32时，物理地址需要4字节对齐，数据类型为FP16时，物理地址需要2字节对齐；虚拟地址不使用，不做参数异常检查，stride需要16字节对齐；dst的宽和高要求可分为以下两种情况：
- 如果ctrl->has_idx等于TD_FALSE，dst的高必须等于src的高。
- 如果ctrl->has_idx等于TD_TRUE，dst的高必须等于src_idx的宽。

【举例】

无。

【相关主题】

无。

ss_mpi_svp_mau_get_sort_tmpbuf_size¶

【描述】

获取排序运算辅助内存字节数。

【语法】

td_s32 ss_mpi_svp_mau_get_sort_tmpbuf_size(ot_svp_blob_type type, td_u32 src_col, td_u32 *size);

【参数】

参数名称	描述	输入/输出
type	排序元素数据类型，数据类型支持OT_SVP_BLOB_TYPE_FP32，OT_SVP_BLOB_TYPE_FP16，OT_SVP_BLOB_TYPE_U32，OT_SVP_BLOB_TYPE_S32, OT_SVP_BLOB_TYPE_U16，OT_SVP_BLOB_TYPE_S16，OT_SVP_BLOB_TYPE_U8，OT_SVP_BLOB_TYPE_S8。	输入
src_col	矩阵中一行待排序元素数目，取值范围[1, 100000]。	输入
size	辅助内存字节数。不能为空。	输出

参数名称

描述

输入/输出

type

排序元素数据类型，数据类型支持OT_SVP_BLOB_TYPE_FP32，OT_SVP_BLOB_TYPE_FP16，OT_SVP_BLOB_TYPE_U32，OT_SVP_BLOB_TYPE_S32, OT_SVP_BLOB_TYPE_U16，OT_SVP_BLOB_TYPE_S16，OT_SVP_BLOB_TYPE_U8，OT_SVP_BLOB_TYPE_S8。

输入

src_col

矩阵中一行待排序元素数目，取值范围[1, 100000]。

输入

size

辅助内存字节数。

不能为空。

输出

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【解决方案差异】

解决方案名称	差异
SS928V100	不支持
SS927V100	不支持

【需求】

头文件：ot_common_svp.h、ot_common_mau.h、ss_mpi_mau.h
库文件：libss_mau.a

【注意】

该接口与ss_mpi_svp_mau_sort配套使用，type和src_col与ss_mpi_svp_mau_sort参数中src->data_matrix的type及width应一致。

【举例】

无。

【相关主题】

ss_mpi_svp_mau_sort

ss_mpi_svp_mau_sort¶

【描述】

计算矩阵每一行数据进行排序。

【语法】

td_s32 ss_mpi_svp_mau_sort(ot_svp_mau_handle *handle, const ot_svp_mau_sort_matrix*src, const ot_svp_blob *src_idx, const ot_svp_mau_sort_ctrl *ctrl, const ot_svp_mau_sort_result *dst);

【参数】

参数名称	描述	输入/输出
handle	handle指针。不能为空。	输出
src	输入矩阵。不能为空。	输入
src_idx	输入矩阵的行索引。如果ctrl信息中has_ idx为TD_TRUE时，不能为空。	输入
ctrl	输入控制信息。不能为空。	输入
dst	输出结果。不能为空。	输出

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【解决方案差异】

解决方案名称	差异
SS928V100	不支持
SS927V100	不支持

【需求】

头文件：ot_common_svp.h、ot_common_mau.h、ss_mpi_mau.h
库文件：libss_mau.a

【注意】

矩阵A在内存中的数据排布如下：

图 1 矩阵内存排布

ss_mpi_svp_mau_get_fir_tmpbuf_size¶

【描述】

获取快速图像检索辅助内存字节数。

【语法】

td_s32 ss_mpi_svp_mau_get_fir_tmpbuf_size (const ot_svp_mau_fir_src *src, td_u32 bucket_num, td_u32 sub_vec_num, td_u32 *size);

【参数】

参数名称	描述	输入/输出
src	检索输入矩阵。	输入
bucket_num	检索使用分桶数目，取值范围：[1, 65535]	输入
sub_vec_num	子空间划分数目，取值范围：{1,2,4,8,16}	输入
size	辅助内存字节数。不能为空。	输出

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【解决方案差异】

解决方案名称	差异
SS928V100	不支持
SS927V100	不支持

【需求】

头文件：ot_common_svp.h、ot_common_mau.h、ss_mpi_mau.h
库文件：libss_mau.a

【注意】

用户需要确保输入左右矩阵的数据中不能含有INF、-INF或者NAN数据，并且输入数值和计算结果都在fp32数据表示有效范围内，否则会导致输出的结果数值中有INF、-INF或NAN，从而使结果数值失去意义。
src->query_item的chn必须为1，num必须为1，height取值范围为[1, 65535]；数据类型仅支持OT_SVP_BLOB_TYPE_FP32和OT_SVP_BLOB_TYPE_FP16；数据类型为FP32时，width取值范围为[1, 8192]，数据类型为FP16时，width取值范围为[1,16384]；数据类型为FP32时，物理地址需要4字节对齐，数据类型为FP16时，物理地址需2字节对齐，虚拟地址不使用，不做参数异常检查；stride需要16字节对齐。
src->bucket_center的chn必须为1，num必须为1，height取值范围为[1, 65535]；数据类型仅支持OT_SVP_BLOB_TYPE_FP32和OT_SVP_BLOB_TYPE_FP16；数据类型为FP32时，width取值范围为[1, 8192]，数据类型为FP16时，width取值范围为[1,16384]；数据类型为FP32时，物理地址需要4字节对齐，数据类型为FP16时，物理地址需2字节对齐，虚拟地址不使用，不做参数异常检查；stride需要16字节对齐。
src->dict_info的chn必须为1，num必须为1，height取值范围为[1, 256]；数据类型仅支持OT_SVP_BLOB_TYPE_FP32和OT_SVP_BLOB_TYPE_FP16；数据类型为FP32时，width取值范围为[1, 8192]，数据类型为FP16时，width取值范围为[1,16384]；数据类型为FP32时，物理地址需要4字节对齐，数据类型为FP16时，物理地址需2字节对齐，虚拟地址不使用，不做参数异常检查；stride需要16字节对齐。
src-> bucket_info的chn必须为1，num必须为1，width必须为4，height取值范围为[1, 65535]；数据类型仅支持OT_SVP_BLOB_TYPE_U32；物理地址需要4字节对齐，虚拟地址不使用，不做参数异常检查；stride需要16字节对齐。
src->query_item，src->bucket_center和src->dict_info的width必须一致，数据类型必须一致。
src->query_item，src->bucket_center和src->dict_info的width必须是ctrl->sub_vec_num乘于8的倍数。
src->bucket_center和src->bucket_info的height必须一致。
bucket_num取值范围为[1, src->bucket_center.shape.whc.height]。

【举例】

无。

【相关主题】

ss_mpi_svp_mau_fir

ss_mpi_svp_mau_fir¶

【描述】

快速图像检索。

【语法】

ss_mpi_svp_mau_fir(ot_svp_mau_handle *handle, const ot_svp_mau_fir_src *src, const ot_svp_mau_fir_ctrl *ctrl, const ot_svp_mau_fir_result *dst);

【参数】

参数名称	描述	输入/输出
handle	handle指针。不能为空。	输出
src	输入矩阵。不能为空。	输入
ctrl	输入控制信息。不能为空。	输入
dst	输出结果。不能为空。	输出

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【解决方案差异】

解决方案名称	差异
SS928V100	不支持
SS927V100	不支持

【需求】

头文件：ot_common_svp.h、ot_common_mau.h、ss_mpi_mau.h
库文件：libss_mau.a

【注意】

矩阵在内存中的数据排布如下：

图 1 矩阵内存排布
用户需要确保输入左右矩阵的数据中不能含有INF、-INF或者NAN数据，并且输入数值和计算结果都在fp32数据表示有效范围内，否则会导致输出的结果数值中有INF、-INF或NAN，从而使结果数值失去意义。
src->query_item的chn必须为1，num必须为1，height取值范围为[1, 65535]；数据类型仅支持OT_SVP_BLOB_TYPE_FP32和OT_SVP_BLOB_TYPE_FP16；数据类型为FP32时，width取值范围为[1, 8192]，数据类型为FP16时，width取值范围为[1,16384]；数据类型为FP32时，物理地址需要4字节对齐，数据类型为FP16时，物理地址需2字节对齐，虚拟地址不使用，不做参数异常检查；stride需要16字节对齐。
src->bucket_center的chn必须为1，num必须为1，height取值范围为[1, 65535]；数据类型仅支持OT_SVP_BLOB_TYPE_FP32和OT_SVP_BLOB_TYPE_FP16；数据类型为FP32时，width取值范围为[1, 8192]，数据类型为FP16时，width取值范围为[1,16384]；数据类型为FP32时，物理地址需要4字节对齐，数据类型为FP16时，物理地址需2字节对齐，虚拟地址不使用，不做参数异常检查；stride需要16字节对齐。
src->dict_info的chn必须为1，num必须为1，height取值范围为[1, 256]；数据类型仅支持OT_SVP_BLOB_TYPE_FP32和OT_SVP_BLOB_TYPE_FP16；数据类型为FP32时，width取值范围为[1, 8192]，数据类型为FP16时，width取值范围为[1,16384]；数据类型为FP32时，物理地址需要4字节对齐，数据类型为FP16时，物理地址需2字节对齐，虚拟地址不使用，不做参数异常检查；stride需要16字节对齐。
src->bucket_info的chn必须为1，num必须为1，width必须为4，height取值范围为[1, 65535]；数据类型仅支持OT_SVP_BLOB_TYPE_U32；物理地址需要4字节对齐，虚拟地址不使用，不做参数异常检查；stride需要16字节对齐。
src->query_item，src->bucket_center和src->dict_info的width必须一致，数据类型必须一致。
src->query_item，src->bucket_center和src->dict_info的width必须是ctrl->sub_vec_num乘于8的倍数。
src->bucket_center和src->bucket_info的height必须一致。
ctrl->is_instant值必须为TD_TRUE或TD_FALSE。
ctrl->bucket_num取值范围为[1, src->bucket_center.shape.whc.height]。
ctrl->feature_db的物理地址必须16字节对齐，虚拟地址不使用，不做参数异常检查。
ctrl->id_db的物理地址必须16字节对齐，虚拟地址不使用，不做参数异常检查。
ctrl->tmp_buf的物理地址必须16字节对齐，虚拟地址不使用，不做参数异常检查，size大于或者等于ss_mpi_svp_mau_get_fir_tmpbuf_size计算结果。
dst->top_n的chn必须等于1，num必须为1，height等于src->query_item.shape.whc.height，width的取值范围为[1, 1024]，物理地址4字节对齐，虚拟地址不使用，不做参数异常检查，stride需要16字节对齐，数据类型必须为OT_SVP_BLOB_TYPE_FP32。
dst->top_n_idx的chn必须等于1，num必须为1，物理地址4字节对齐，虚拟地址不使用，不做参数异常检查，stride需要16字节对齐，数据类型必须为OT_SVP_BLOB_TYPE_U32，dst->top_n_idx的宽和高必须与dst->top_n一致。
dst->top_n的值为U32的最大值（0xFFFFFFFF）时，表示检索结果不足dst->top_n.shape.whc.with。

【举例】

无。

【相关主题】

ss_mpi_svp_mau_get_fir_tmpbuf_size

ss_mpi_svp_mau_query¶

【描述】

任务状态查询。

【语法】

td_s32 ss_mpi_svp_mau_query(ot_svp_mau_id mau_id, ot_svp_mau_handle handle, td_bool *is_finish, td_bool is_block);

【参数】

参数名称	描述	输入/输出
mau_id	任务所运行的MAU核ID。	输入
handle	任务的handle。取值范围：(-1, 0x0FFFFFFF)。	输入
is_finish	任务是否完成。不能为空。	输出
is_block	是否阻塞查询。	输入

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_svp.h、ot_common_mau.h、ss_mpi_mau.h
库文件：libss_mau.a

【注意】

输入的handle必须为调用ss_mpi_svp_mau_matrix_mul，ss_mpi_svp_mau_cos_dist或者ss_mpi_svp_mau_euclid_dist函数返回的handle。

【举例】

无。

【相关主题】

无。

ss_mpi_svp_mau_add_mem_info¶

【描述】

记录内存信息。

【语法】

td_s32 ss_mpi_svp_mau_add_mem_info(const ot_svp_mem_info * mem_info);

【参数】

参数名称	描述	输入/输出
mem_info	内存信息指针。不能为空，申请使用的内存需要是带cache的。	输入

参数名称

描述

输入/输出

mem_info

内存信息指针。

不能为空，申请使用的内存需要是带cache的。

输入

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_svp.h、ot_common_mau.h、ss_mpi_mau.h
库文件：libss_mau.a

【注意】

记录内存地址信息，用于减少内核态内存映射次数，提升效率。
内存地址信息的记录是通过链表进行管理，链表长度默认值为32，链表长度可通过模块参数mau_max_mem_info_num进行配置。
若没有调用ss_mpi_svp_mau_add_mem_info预先把索引矩阵地址信息记录到系统，那么在之后计算中每次都会Map/Unmap操作索引矩阵内核态的虚拟地址，效率会比较低。
必须与ss_mpi_svp_mau_rm_mem_info成对匹配使用。
建议先把矩阵运算要用到的索引矩阵地址信息调用此接口记录到系统。当不再使用时调用ss_mpi_svp_mau_rm_mem_info把索引矩阵地址信息移除。只需要在初始化时把索引矩阵地址信息记录，后续可以直接使用，直到不再使用时才移除。
物理地址4字节对齐。
mem_info ->virt_addr不使用，不做参数异常检查。
mem_info ->size不能为0。
mem info内存由用户释放，记录的mem info内存要在移除后才能被释放。

【举例】

无。

【相关主题】

无。

ss_mpi_svp_mau_rm_mem_info¶

【描述】

移除内存信息。

【语法】

td_s32 ss_mpi_svp_mau_rm_mem_info (const ot_svp_mem_info* mem_info);

【参数】

参数名称	描述	输入/输出
mem_info	内存信息指针。不能为空	输入

参数名称

描述

输入/输出

mem_info

内存信息指针。

不能为空

输入

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_svp.h、ot_common_mau.h、ss_mpi_mau.h
库文件：libss_mau.a

【注意】

如果mem info不再使用，需要将记录的mem info地址信息从链表中移除。
必须与ss_mpi_svp_mau_add_mem_info成对匹配使用。
物理地址4字节对齐。
mem_info ->virt_addr不使用，不做参数异常检查。
mem_info ->size不能为0。
mem info内存由用户释放，记录的mem info内存要在移除后才能被释放。

【举例】

无。

【相关主题】

无。

数据类型和数据结构¶

MAU相关数据类型、数据结构定义如下：

ot_svp_blob_type¶

【说明】

定义blob的数据内存排布。

【定义】

typedef enum {
    OT_SVP_BLOB_TYPE_S20Q12       =  0x0,
    OT_SVP_BLOB_TYPE_U8            =  0x1,
    OT_SVP_BLOB_TYPE_YVU420SP     =  0x2,  /* channel = 3 */
    OT_SVP_BLOB_TYPE_YVU422SP     =  0x3,  /* channel = 3 */
    OT_SVP_BLOB_TYPE_VEC_S20Q12   =  0x4,
    OT_SVP_BLOB_TYPE_SEQ_S20Q12   =  0x5,
    OT_SVP_BLOB_TYPE_BBOX_S20Q12  =  0x6,
    OT_SVP_BLOB_TYPE_BSI_SQ32      =  0x7,
    OT_SVP_BLOB_TYPE_S12Q20        =  0x8,
    OT_SVP_BLOB_TYPE_VEC_S12Q20   =  0x9,
    OT_SVP_BLOB_TYPE_S32           =  0xa,
    OT_SVP_BLOB_TYPE_U32           =  0xb,
    OT_SVP_BLOB_TYPE_FP32          =  0xc,
    OT_SVP_BLOB_TYPE_FP16          =  0xd,
    OT_SVP_BLOB_TYPE_S8            =  0xe,
    OT_SVP_BLOB_TYPE_S16           =  0xf,
    OT_SVP_BLOB_TYPE_U16           =  0x10,
    OT_SVP_BLOB_TYPE_BUTT
}ot_svp_blob_type;

【成员】

成员名称	描述
OT_SVP_BLOB_TYPE_S20Q12	Blob数据元素为S20Q12类型，参考图2
OT_SVP_BLOB_TYPE_U8	Blob数据元素为U8类型，参考图3
OT_SVP_BLOB_TYPE_YVU420SP	Blob数据内存排布为YVU420SP，参考图4。
OT_SVP_BLOB_TYPE_YVU422SP	Blob数据内存排布为YVU422SP，参考图5。
OT_SVP_BLOB_TYPE_VEC_S20Q12	Blob中存储向量，每个元素为S20Q12类型，参考图6。
OT_SVP_BLOB_TYPE_SEQ_S20Q12	Blob中存储序列，数据元素为S20Q12类型，排布见图7。
OT_SVP_BLOB_TYPE_BBOX_S20Q12	Blob中存储坐标，数据元素为S20Q12类型，排布见图8。
OT_SVP_BLOB_TYPE_BSI_SQ32	Blob中存储坐标、分值和类别，数据元素为32bit的量化数据，排布见图9。
OT_SVP_BLOB_TYPE_S12Q20	Blob数据元素为S12Q20类型，参考图10
OT_SVP_BLOB_TYPE_VEC_S12Q20	Blob中存储向量，每个元素为S12Q20类型，参考图11。
OT_SVP_BLOB_TYPE_S32	Blob数据元素为32bit有符号整型，参考图12
OT_SVP_BLOB_TYPE_U32	Blob数据元素为32bit无符号整型，参考图13
OT_SVP_BLOB_TYPE_FP32	Blob数据元素为32bit浮点型，参考图14
OT_SVP_BLOB_TYPE_FP16	Blob数据元素为16bit浮点型，参考图15
OT_SVP_BLOB_TYPE_S8	Blob数据元素为8bit有符号整型，参考图16
OT_SVP_BLOB_TYPE_S16	Blob数据元素为16bit有符号整型，参考图17
OT_SVP_BLOB_TYPE_U16	Blob数据元素为16bit无符号整型，参考图18

【注意事项】

无。

【相关数据类型及接口】

ot_svp_blob

ot_svp_blob¶

【说明】

定义多个连续存放的blob信息。

【定义】

typedef struct {
     ot_svp_blob_type type;
     td_u32 stride;
     td_u64 virt_addr;
     td_u64 phys_addr;      
     td_u32 num;        
     union {
        struct {
            td_u32 width;    
            td_u32 height;   
            td_u32 chn;
        } whc;
        struct {
            td_u32 dim;
            td_u64 virt_addr_step;  
        } seq;
    } shape;
} ot_svp_blob;

【成员】

成员名称	描述
type	Blob类型。 type取值范围：[OT_SVP_BLOB_TYPE_S20Q12, OT_SVP_BLOB_TYPE_BUTT)。
stride	Blob中单行数据的对齐后的字节数，要求16字节对齐。
virt_addr	Blob首虚拟地址。
phys_addr	Blob首物理地址。
num	表示连续内存块的数目，若一帧数据对应一个块，则表示blob中有num帧。 type为YVU420SP\YVU422SP\U8\SEQ_S20Q12\ BSI_SQ32时，取值范围：[1, 256]。 type为S20Q12\S12Q20\VEC_S20Q12\VEC_S12Q20时，取值范围：[1, 5000]。 type为BBOX_S20Q12时，取值范围：[1, 1]。
width	Blob 的宽度。 type为YVU420SP\YVU422SP\U8时，取值范围：[8, 4096]。 type为S20Q12\S12Q20时，取值范围：[1, 65535]。 type为VEC_S20Q12\VEC_S12Q20时，取值范围：[1, 0xFFFFFFFF]。 type为BBOX_S20Q12时，取值为4。 type为BSI_SQ32时，取值范围：[1, 10000]
height	Blob的高度。 type为YVU420SP\YVU422SP\U8时，取值范围：[8, 4096]。 type为S20Q12\S12Q20时，取值范围：[1, 0xFFFFFFFF]。 type为VEC_S20Q12\VEC_S12Q20时，取值范围：[1, 1]。 type为BBOX_S20Q12时，取值范围：[1,5000]。 type为BSI_SQ32时，取值为6。
chn	Blob中的通道数。 type为YVU420SP\YVU422SP时，取值为3 type为U8时，取值为1或3 type为S20Q12\S12Q20时，取值范围：[1, 0xFFFFFFFF] type为VEC_S20Q12\S12Q20时，取值范围：[1, 1] type为BBOX_S20Q12时，取值为1。 type为BSI_SQ32时，取值范围：[1, 256]。
dim	向量的长度，仅用作RNN\LSTM数据的表示。 type为SEQ_S20Q12时，取值范围：[1, 0xFFFFFFFF]
virt_addr_step	数组地址，数组元素表示每段序列有多少个向量。

【注意事项】

无。

【相关数据类型及接口】

ot_svp_blob_type

ot_svp_src_blob¶

【说明】

定义源序列。

【定义】

typedef ot_svp_blob  ot_svp_src_blob;

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

ot_svp_blob
ot_svp_dst_blob

ot_svp_dst_blob¶

【说明】

定义输出序列。

【定义】

typedef ot_svp_blob  ot_svp_dst_blob;

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

ot_svp_blob
ot_svp_src_blob

ot_svp_mem_info¶

【说明】

定义一维内存信息。

【定义】

typedef struct {
    td_u64  phys_addr; 
    td_u64  virt_addr; 
    td_u32  size; 
} ot_svp_mem_info;

【成员】

成员名称	描述
phys_addr	内存块物理地址。
virt_addr	内存块虚拟地址。
size	内存块字节数。见图19。

【注意事项】

无。

【相关数据类型及接口】

ot_svp_src_mem_info
ot_svp_dst_mem_info

ot_svp_src_mem_info¶

【说明】

定义一维输入内存信息。

【定义】

typedef ot_svp_mem_info ot_svp_src_mem_info;

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

ot_svp_mem_info
ot_svp_dst_mem_info

ot_svp_dst_mem_info¶

【说明】

定义一维输出内存信息。

【定义】

typedef ot_svp_mem_info ot_svp_dst_mem_info;

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

ot_svp_mem_info
ot_svp_src_mem_info

ot_svp_mau_handle¶

【说明】

定义MAU的句柄。

【定义】

typedef td_s32 ot_svp_mau_handle;

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

无。

ot_svp_mau_double_matrix¶

【说明】

定义左右矩阵信息。

【定义】

typedef struct {
    ot_svp_blob  left_matrix; /* RW;left matrix */
    ot_svp_blob  right_matrix; /* RW;right matrix */
} ot_svp_mau_double_matrix;

【成员】

成员名称	描述
left_matrix	左矩阵信息。
right_matrix	右矩阵信息。

【注意事项】

无。

【相关数据类型及接口】

ot_svp_blob

ot_svp_mau_src_double_matrix¶

【说明】

定义输入左右矩阵信息。

【定义】

typedef ot_svp_mau_double_matrix ot_svp_mau_src_double_matrix;

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

ot_svp_mau_double_matrix

ot_svp_mau_out_type¶

【说明】

定义输出结果类型。

【定义】

typedef enum {
    OT_SVP_MAU_OUT_OP_RESULT = 0x0,
    OT_SVP_MAU_OUT_TOP_N       = 0x1,
    OT_SVP_MAU_OUT_BOTH       = 0x2,
    OT_SVP_MAU_OUT_BUTT
} ot_svp_mau_out_type;

【成员】

成员名称	描述
OT_SVP_MAU_OUT_OP_RESULT	表示仅输出算子运算结果。
OT_SVP_MAU_OUT_TOP_N	表示仅输出Top_n结果。
OT_SVP_MAU_OUT_BOTH	表示输出算子运算结果和Top_n结果。

【注意事项】

无。

【相关数据类型及接口】

无。

ot_svp_mau_id¶

【说明】

定义MAU核ID。

【定义】

typedef enum {
    SVP_MAU_ID_0 = 0x0;
    SVP_MAU_ID_BUTT
} ot_svp_mau_id;

【成员】

成员名称	描述
SVP_MAU_ID_0	表示ID为0的MAU核。

【注意事项】

无。

【相关数据类型及接口】

无。

ot_svp_mau_ctrl¶

【说明】

定义MAU控制信息。

【定义】

typedef struct {
    ot_svp_mau_id mau_id;
    ot_svp_mau_out_type out_type;
    td_bool fp32_to_fp16_en;
    td_bool has_left_idx;
    td_bool has_right_idx;
    td_bool is_instant;
} ot_svp_mau_ctrl;

【成员】

成员名称	描述
mau_id	执行任务的MAU核ID。取值范围：[SVP_MAU_ID_0, SVP_MAU_ID_BUTT)
out_type	输出结果类型。
has_left_idx	左矩阵是否使用索引获取行向量进行计算。
has_right_idx	右矩阵是否使用索引获取行向量进行计算。
fp32_to_fp16_en	输入fp32类型的数据是否转为fp16进行计算。
is_instant	是否及时返回结果。

【注意事项】

如果输入左矩阵数据类型为fp32，右矩阵数据类型为fp16，fp32_to_fp16_en必须为TD_TRUE。
如果输入左矩阵数据类型为fp16，右矩阵数据类型为fp32，fp32_to_fp16_en必须为TD_TRUE。
如果输入左矩阵数据类型为fp16，右矩阵数据类型为fp16，fp32_to_fp16_en必须为TD_FALSE。
如果输入左矩阵数据类型为fp32，右矩阵数据类型为fp32，fp32_to_fp16_en可以为TD_TRUE或TD_FALSE。

【相关数据类型及接口】

ot_svp_mau_id
ot_svp_mau_out_type

ot_svp_mau_dist_result¶

【说明】

定义矩阵距离结果。

【定义】

typedef struct {
    ot_svp_blob op_result;
    ot_svp_blob top_n;
    ot_svp_blob top_n_idx;
} ot_svp_mau_dist_result;

【成员】

成员名称	描述
op_result	算子运算结果。
top_n	Top_n结果。
top_n_idx	Top_n结果对应的行或者行索引。

【注意事项】

op_result数据类型必须为OT_SVP_BLOB_TYPE_FP32。
top_n数据类型必须为OT_SVP_BLOB_TYPE_FP32。
top_n_idx数据类型必须为OT_SVP_BLOB_TYPE_U32。

【相关数据类型及接口】

ot_svp_blob

ot_svp_mau_mod_param¶

【说明】

模块参数。

【定义】

typedef struct {
    td_u16  mau_max_mem_info_num; 
    td_u16  mau_max_node_num; 
    td_u8   mau_power_save_en; 
    td_u8   reserved;
} ot_svp_mau_mod_param;

【成员】

成员名称	描述
mau_max_mem_info_num	最大可记录mem_info个数。取值范围：[16, 512]。默认值：32。
mau_max_node_num	任务队列最大节点数。取值范围：[16, 512]。默认值：512。
mau_power_save_en	是否开启低功耗。取值范围：[0, 1]。默认值：1。
reserved	保留字节，用于字节对齐。

【注意事项】

如果传入的模块参数数值超过取值范围，驱动会使用默认的模块参数值进行初始化。

【相关数据类型及接口】

无。

ot_svp_mau_transpose_ctrl¶

【说明】

定义矩阵转置控制信息。

【定义】

typedef struct {
    ot_svp_mau_id mau_id;
    td_bool has_idx;
    td_bool is_instant;
} ot_svp_mau_transpose_ctrl;

【成员】

成员名称

描述

mau_id

执行任务的MAU核ID。

取值范围：[SVP_MAU_ID_0, SVP_MAU_ID_BUTT)

has_idx

矩阵是否使用索引获取行向量进行计算。

is_instant

是否及时返回结果。

【注意事项】

无。

【相关数据类型及接口】

ot_svp_mau_id

ot_svp_mau_vector_op_mode¶

【说明】

定义向量运算模式。

【定义】

typedef enum {
    OT_SVP_MAU_VECTOR_OP_MODE_SUB = 0x0,
    OT_SVP_MAU_VECTOR_OP_MODE_SUB_ABS = 0x1,
    OT_SVP_MAU_VECTOR_OP_MODE_ADD = 0x2,
    OT_SVP_MAU_VECTOR_OP_MODE_ADD_ABS = 0x3,
    OT_SVP_MAU_VECTOR_OP_MODE_BUTT
} ot_svp_mau_vector_op_mode;

【成员】

成员名称	描述
OT_SVP_MAU_VECTOR_OP_MODE_SUB	表示向量各元素依次相减。
OT_SVP_MAU_VECTOR_OP_MODE_SUB_ABS	表示向量各元素依次相减的绝对值
OT_SVP_MAU_VECTOR_OP_MODE_ADD	表示向量各元素依次相加
OT_SVP_MAU_VECTOR_OP_MODE_ADD_ABS	表示向量各元素依次相加的绝对值

【注意事项】

无。

【相关数据类型及接口】

无。

ot_svp_mau_vector_op_ctrl¶

【说明】

定义向量运算控制信息。

【定义】

typedef struct {
    ot_svp_mau_id mau_id;
    ot_svp_mau_vector_op_mode mode;
    td_bool fp32_to_fp16_en;
    td_bool has_left_idx;
    td_bool has_right_idx;
    td_bool is_instant;
} ot_svp_mau_vector_op_ctrl;

【成员】

成员名称	描述
mau_id	执行任务的MAU核ID。取值范围：[SVP_MAU_ID_0, SVP_MAU_ID_BUTT)
mode	向量运算模式。
has_left_idx	左矩阵是否使用索引获取行向量进行计算。
has_right_idx	右矩阵是否使用索引获取行向量进行计算。
fp32_to_fp16_en	输入fp32类型的数据是否转为fp16进行计算。
is_instant	是否及时返回结果。

【注意事项】

如果输入左矩阵数据类型为fp32，右矩阵数据类型为fp16，fp32_to_fp16_en必须为TD_TRUE。
如果输入左矩阵数据类型为fp16，右矩阵数据类型为fp32，fp32_to_fp16_en必须为TD_TRUE。
如果输入左矩阵数据类型为fp16，右矩阵数据类型为fp16，fp32_to_fp16_en必须为TD_FALSE。
如果输入左矩阵数据类型为fp32，右矩阵数据类型为fp32，fp32_to_fp16_en可以为TD_TRUE或TD_FALSE。

【相关数据类型及接口】

ot_svp_mau_id
ot_svp_mau_vector_op_mode

ot_svp_mau_type_convert_mode¶

【说明】

定义数据类型转换模式。

【定义】

typedef enum {
    OT_SVP_MAU_TYPE_CONVERT_MODE_FP32_TO_FP16   = 0x0,
    OT_SVP_MAU_TYPE_CONVERT_MODE_FP16_TO_FP32  = 0x1,
    OT_SVP_MAU_TYPE_CONVERT_MODE_BUTT
} ot_svp_mau_type_convert_mode;

【成员】

成员名称	描述
OT_SVP_MAU_TYPE_CONVERT_MODE_FP32_TO_FP16	表示数据类型由FP32转换为FP16。
OT_SVP_MAU_TYPE_CONVERT_MODE_FP16_TO_FP32	表示数据类型由FP16转换为FP32。

【注意事项】

无。

【相关数据类型及接口】

无。

ot_svp_mau_type_convert_ctrl¶

【说明】

定义数据类型转换控制信息。

【定义】

typedef struct {
    ot_svp_mau_id mau_id;
    ot_svp_mau_type_convert_mode mode;
    td_bool has_idx;
    td_bool is_instant;
} ot_svp_mau_type_convert_ctrl;

【成员】

成员名称	描述
mau_id	执行任务的MAU核ID。取值范围：[SVP_MAU_ID_0, SVP_MAU_ID_BUTT)
mode	数据类型转换模式。
has_idx	矩阵是否使用索引获取行向量进行计算。
is_instant	是否及时返回结果。

【注意事项】

如果输入矩阵数据类型为fp32，输出矩阵数据类型必须为fp16，mode必须为OT_SVP_MAU_TYPE_CONVERT_MODE_FP32_TO_FP16。
如果输入矩阵数据类型为fp16，输出矩阵数据类型必须为fp32，mode必须为OT_SVP_MAU_TYPE_CONVERT_MODE_FP16_TO_FP32。

【相关数据类型及接口】

ot_svp_mau_id
ot_svp_mau_type_convert_mode

ot_svp_mau_sort_mode¶

【说明】

定义排序模式。

【定义】

typedef enum {
    OT_SVP_MAU_SORT_MODE_DESC = 0x0,
    OT_SVP_MAU_SORT_MODE_ASC  = 0x1,
    OT_SVP_MAU_SORT_MODE_BUTT
} ot_svp_mau_sort_mode;

【成员】

成员名称	描述
OT_SVP_MAU_SORT_MODE_DESC	表示降序排序。
OT_SVP_MAU_SORT_MODE_ASC	表示升序排序

【注意事项】

无。

【相关数据类型及接口】

无。

ot_svp_mau_sort_matrix¶

【说明】

定义排序矩阵信息。

【定义】

typedef struct {
    ot_svp_blob data_matrix;
    ot_svp_blob id_matrix;
} ot_svp_mau_sort_matrix;

【成员】

成员名称

描述

data_matrix

待排序元素矩阵。

数据类型支持OT_SVP_BLOB_TYPE_FP32，OT_SVP_BLOB_TYPE_FP16, OT_SVP_BLOB_TYPE_U32, OT_SVP_BLOB_TYPE_S32, OT_SVP_BLOB_TYPE_U16, OT_SVP_BLOB_TYPE_S16, OT_SVP_BLOB_TYPE_U8, OT_SVP_BLOB_TYPE_S8。

宽的取值范围[1, 100000]，高的取值范围[1, 100000]，chn取值为1，num取值为1，虚拟地址不使用，不做参数异常检查，stride 16字节对齐。

物理地址依据数据类对齐。FP32，U32，S32时，4字节对齐；F P16，U16，S16时，2字节对齐；U8，S8时，4字节对齐。

id_matrix

data_matrix各元素对应的id。

数据类型仅支持OT_SVP_BLOB_TYPE_U32。

【注意事项】

data_matrix数据类型为OT_SVP_BLOB_TYPE_FP32，OT_SVP_BLOB_TYPE_FP16, OT_SVP_BLOB_TYPE_U32, OT_SVP_BLOB_TYPE_S32, OT_SVP_BLOB_TYPE_U16, OT_SVP_BLOB_TYPE_S16, OT_SVP_BLOB_TYPE_U8, OT_SVP_BLOB_TYPE_S8之一。
id_matrix数据类型必须为OT_SVP_BLOB_TYPE_U32。

【相关数据类型及接口】

ot_svp_blob

ot_svp_mau_sort_ctrl¶

【说明】

定义排序控制信息。

【定义】

typedef struct {
    ot_svp_mau_id mau_id;
    ot_svp_mau_sort_mode mode;
    td_bool has_idx;
    td_bool has_id_matrix;
    td_bool is_instant;
    ot_svp_mem_info tmp_buf;
} ot_svp_mau_sort_ctrl;

【成员】

成员名称	描述
mau_id	执行任务的MAU核ID。取值范围：[SVP_MAU_ID_0, SVP_MAU_ID_BUTT)
mode	排序规则。
has_idx	矩阵是否使用索引获取行向量进行计算。
has_id_matrix	矩阵是否使用id矩阵进行索引运算。
is_instant	是否及时返回结果。
tmp_buf	辅助内存

【注意事项】

has_idx 和has_id_matrix不能同时为TD_TRUE。
辅助内存大小必须大于或等于由ss_mpi_svp_mau_get_sort_tmpbuf_size计算大小。

【相关数据类型及接口】

ot_svp_mau_id

ot_svp_mau_sort_result¶

【说明】

定义排序结果。

【定义】

typedef struct {
    ot_svp_blob top_n;
    ot_svp_blob top_n_idx;
} ot_svp_mau_sort_result;

【成员】

成员名称	描述
top_n	top_n结果。
top_n_idx	top_n结果对应索引。

【注意事项】

top_n数据类型必须与源数据类型一致。
top_n_idx数据类型必须为OT_SVP_BLOB_TYPE_U32。

【相关数据类型及接口】

ot_svp_blob

ot_svp_mau_fir_src¶

【说明】

定义矩阵距离结果。

【定义】

typedef struct {
    ot_svp_blob query_item;
    ot_svp_blob bucket_center;
    ot_svp_blob dict_info;
    ot_svp_blob bucket_info;
} ot_svp_mau_fir_src;

【成员】

成员名称	描述
query_item	待查询向量。
bucket_center	分桶中心信息。
dict_info	字典信息。
bucket_info	分桶信息

【注意事项】

query_item, bucket_center 和dict_info的width必须为一致。
bucket_center 和bucket_info 的height必须一致。
bucket_info的width必须为4。

【相关数据类型及接口】

ot_svp_blob

ot_svp_mau_fir_result¶

【说明】

定义快速图像检索结果。

【定义】

typedef ot_svp_mau_sort_result ot_svp_mau_fir_result;

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

ot_svp_mau_sort_result

ot_svp_mau_fir_ctrl¶

【说明】

定义快速图像检索控制信息。

【定义】

typedef struct {
    ot_svp_mau_id mau_id;
    td_bool is_instant;
    td_u16 sub_vec_num;
    td_u16 bucket_num;
    ot_svp_mem_info feature_db; 
    ot_svp_mem_info id_db;
    ot_svp_mem_info tmp_buf;;
} ot_svp_mau_fir_ctrl;

【成员】

成员名称	描述
mau_id	执行任务的MAU核ID。取值范围：[SVP_MAU_ID_0, SVP_MAU_ID_BUTT)
is_instant	是否及时返回结果。
sub_vec_num	子空间划分数目，取值范围为{1,2,4,8,16}。
bucket_num	使用分桶数目，取值范围为[1,65535]。
feature_db	特征底库。物理地址必须16字节对齐，虚拟地址不使用，不做参数异常检查。
id_db	索引底库。物理地址必须16字节对齐，虚拟地址不使用，不做参数异常检查。
tmp_buf	辅助内存。物理地址必须16字节对齐，虚拟地址不使用，不做参数异常检查。

【注意事项】

无。

【相关数据类型及接口】

ot_svp_blob

错误码¶

MAU模块API错误码如下所示。

表 1 MAU模块API错误码

错误代码	宏定义	描述
0xa03e8001	OT_ERR_SVP_MAU_INVALID_DEV_ID	设备ID超出合法范围
0xa03e8003	OT_ERR_SVP_MAU_INVALID_CHN_ID	通道组号错误或无效区域句柄
0xa03e8007	OT_ERR_SVP_MAU_ILLEGAL_PARAM	参数超出合法范围
0xa03e8008	OT_ERR_SVP_MAU_EXIST	重复创建已存在的设备、通道或资源
0xa03e8009	OT_ERR_SVP_MAU_UNEXIST	试图使用或者销毁不存在的设备、通道或者资源
0xa03e800a	OT_ERR_SVP_MAU_NULL_PTR	函数参数中有空指针
0xa03e800b	OT_ERR_SVP_MAU_NOT_CFG	模块没有配置
0xa03e800c	OT_ERR_SVP_MAU_NOT_SUPPORT	不支持的参数或者功能
0xa03e800d	OT_ERR_SVP_MAU_NOT_PERM	该操作不允许，如试图修改静态配置参数
0xa03e8014	OT_ERR_SVP_MAU_NO_MEM	分配内存失败，如系统内存不足
0xa03e8015	OT_ERR_SVP_MAU_NO_BUF	分配缓存失败，如申请的图像缓冲区太大
0xa03e8016	OT_ERR_SVP_MAU_BUF_EMPTY	缓冲区中无数据
0xa03e8017	OT_ERR_SVP_MAU_BUF_FULL	缓冲区中数据满
0xa03e8018	OT_ERR_SVP_MAU_NOT_READY	系统没有初始化或没有加载相应模块
0xa03e8021	OT_ERR_SVP_MAU_BAD_ADDR	地址非法
0xa03e8022	OT_ERR_SVP_MAU_BUSY	系统忙
0xa03e8040	OT_ERR_SVP_MAU_SYS_TIMEOUT	系统超时
0xa03e8041	OT_ERR_SVP_MAU_QUERY_TIMEOUT	Query查询超时
0xa03e8042	OT_ERR_SVP_MAU_CFG_ERR	配置错误
0xa03e8043	OT_ERR_SVP_MAU_BUS_ERR	总线错误
0xa03e8044	OT_ERR_SVP_MAU_OPEN_FILE	打开文件失败
0xa03e8045	OT_ERR_SVP_MAU_READ_FILE	读文件失败

Proc调试信息¶

概述¶

调试信息采用了Linux下的proc文件系统，可实时反映当前系统的运行状态，所记录的信息可供问题定位及分析时使用。

【文件目录】

/proc/umap

【信息查看方法】

在控制台上可以使用cat命令查看信息，cat /proc/umap/mau；也可以使用其他常用的文件操作命令，例如 cp /proc/umap/mau ./，将文件拷贝到当前目录。
在应用程序中可以将上述文件当作普通只读文件进行读操作，例如fopen、fread等。

说明： 参数在描述时有以下2种情况需要注意：

取值为{0, 1}的参数，如未列出具体取值和含义的对应关系，则参数为1时表示肯定，为0时表示否定。

取值为{aaa, bbb, ccc}的参数，未列出具体取值和含义的对应关系，但可直接根据取值aaa、bbb或ccc判断参数含义

Proc信息说明¶

【调试信息】

# cat /proc/umap/mau
 
[MAU] Version: [Vx.x.x.x B0xx Release], Build Time[mm  dd yyyy, hh:mm:ss]
------------------mau module param------------------------------------
 mau_save_power   mau_max_mem_info_num    mau_max_node_num
                1                         32                    512
 
---------------------------mau queue info--------------------------------
   core_id      wait      busy   wait_cur_id   wait_end_id   busy_cur_id   
         0         0        -1             0             0             0             
   busy_end_id
               0
 
---------------------------mau task info---------------------------------
   core_id    handle   task_finish   last_id   task_id   handle_wrap   
          0          0               0           0          0              0 
   finish_wrap   free_mem_info_num   busy_mem_info_num
               0                     32                      0
 
---------------------------mau runtime info-----------------------------
   core_id  last_instant   irq_cnt_per_sec   max_irq_cnt_per_sec  
          0               0                    0                         0  
   total_irq_cnt_last_sec  total_irq_cnt    query_timeout_cnt
                            0                0                        0
  sys_timeout_cnt   cfg_err_cnt   bus_err_cnt   cur_irq_time    
                   0                0             0              0        
   max_irq_time  irq_time_last_sec  max_irq_time_per_sec    total_irq_time   
                0                    24                         0                  0   
   last_task_hw_time  run_time
                      0_          8
--------------------------mau invoke info------------------------------
   core_id    matrix_mul    cos_dist    euclid_dist
          0               0            0                0    
manhattan_dist     transpose     vector_op  type_convert     sort        fir
            0             0            0             0       0         0

【调试信息分析】

记录当前MAU工作状态资源信息，主要包括MAU队列状态信息，任务状态信息，运行时状态信息和调用信息。

【参数说明】

参数		描述
mau module param MAU 模块参数	mau_save_power	低功耗标志。 0：关闭低功耗； 1：打开低功耗。
	mau_max_mem_info_num	最大能记录的mem info个数, 取值范围：[16, 512]。
	mau_max_node_num	最大任务队列节点个数，取值范围：[16, 512]。
mau queue info MAU队列信息	core_id	MAU 核ID。
	wait	等待队列编号（0或1）。
	busy	正在调度队列编号（0，1或-1），-1表示MAU硬件空闲。
	wait_cur_id	等待队列的首个有效任务ID。
	wait_end_id	等待队列的末尾有效任务ID + 1。
	busy_cur_id	调度队列的首个有效任务ID。
	busy_end_id	调度队列的末尾有效任务ID + 1。
mau task info MAU TASK相关信息	core_id	MAU 核ID。
	handle	当前可分配的任务handle号。
	task_finish	当前已完成任务的个数。
	last_id	上一次中断完成的任务ID。
	task_id	本次中断完成的任务ID。
	handle_wrap	用户handle号分配发生回写的次数。
	finish_wrap	完成任务数发生回写的次数。
	free_mem_info_num	空闲mem info链表节点数。
	busy_mem_info_num	已使用mem info链表节点数。
mau runtime info MAU运行时相关信息	core_id	MAU核ID。
	last_instant	用户最后一次提交任务时传入的is_instant值。
	irq_cnt_per_sec	最近一次的1秒内中断执行次数。
	max_irq_cnt_per_sec	历史上的1秒内最大的中断执行次数。
	total_irq_cnt_last_sec	上一秒上报中断总次数。
	total_irq_cnt	MAU产生中断的总次数。
	query_timeout_cnt	MAU查询超时中断次数。
	sys_timeout_cnt	MAU系统超时次数。
	cfg_err_cnt	MAU配置错误中断次数。
	bus_err_cnt	MAU总线错误次数。
	cur_irq_time	最近一次执行中断的执行耗时。单位：us。
	max_irq_time	执行一次中断的最大耗时。单位：us。
	irq_time_last_sec	最近一秒执行中断的执行耗时。单位：us。
	max_irq_time_per_sec	历史上一秒执行中断的最大执行耗时。单位：us。
	total_irq_time	中断处理总时间。单位：us。
	last_task_hw_time	最近一个任务硬件执行耗时。单位：us。
	run_time	MAU运行总时间。单位：s。
mau invoke infoMAU调用信息	core_id	MAU核ID。
	matrix_mul	计算矩阵乘法的次数。
	cos_dist	计算余弦距离的次数。
	euclid_dist	计算欧式距离的次数。
	manhattan_dist	计算曼哈顿距离的次数。
	transpose	计算矩阵转置的次数。
	vector_op	计算向量运算的次数。
	type_convert	计算数据类型转换的次数。
	sort	计算排序运算的次数。
	fir	计算快速图像检索的次数。

DPU_RECT¶

概述¶

DPU(Depth Process Unit)为_识别_分析系统中的深度处理单元。用户基于DPU对输入的左图像和右图像经过校正和匹配计算得出深度图。DPU分为校正(DPU_RECT)和匹配(DPU_MATCH)两个模块，同时使用，也可单独使用。DPU_RECT对输入的左图像和右图像进行校正。

功能描述¶

重要概念¶

组(GROUP)

DPU_RECT对用户提供组（GROUP）的概念。最大可用数为 16 个，各组分时复用 DPU_RECT硬件。
通道(CHANNEL )

DPU_RECT组的通道。每组包含两个通道，分为左右两通道。
管道(PIPE)

DPU_RECT组的管道。每组包含两个管道，分为左右两管道。
ot_dpu_rect_mem_info内存排布

图 1 ot_dpu_rect_mem_info数据内存示意

调用流程¶

典型场景调用流程按是否绑定目标场景分为如图1和图2两种。绑定场景:支持VI或者VPSS作为DPU_RECT源，DPU_MATCH作为DPU_RECT的目标。

注意：DPU RECT绑定前端模块接收视频帧时，内部会做同步处理，不满足同步要求的帧会被丢弃。

图 1 DPU_RECT无绑定目标场景调用流程

图 2 DPU_RECT绑定目标场景调用流程

API参考¶

该功能模块为用户提供以下MPI:

ss_mpi_dpu_rect_load_lut：加载查找表。
ss_mpi_dpu_rect_unload_lut：卸载查找表。
ss_mpi_dpu_rect_create_grp：创建组。
ss_mpi_dpu_rect_destroy_grp：销毁组。
ss_mpi_dpu_rect_set_grp_attr：设置组属性。
ss_mpi_dpu_rect_get_grp_attr：获取组属性。
ss_mpi_dpu_rect_start_grp：启用组。
ss_mpi_dpu_rect_stop_grp：禁用组。
ss_mpi_dpu_rect_set_chn_attr：设置通道属性。
ss_mpi_dpu_rect_get_chn_attr：获取通道属性。
ss_mpi_dpu_rect_enable_chn：启用通道。
ss_mpi_dpu_rect_disable_chn：禁用通道。
ss_mpi_dpu_rect_send_frame：用户发送数据。
ss_mpi_dpu_rect_get_frame：用户从通道获取一帧处理完成的图像。
ss_mpi_dpu_rect_release_frame：用户释放一帧通道图像。

ss_mpi_dpu_rect_load_lut¶

【描述】

加载查找表。

【语法】

td_s32 ss_mpi_dpu_rect_load_lut(const ot_dpu_rect_mem_info *lut_mem, ot_dpu_rect_lut_id *rect_lut_id);

【参数】

参数名称

描述

输入/输出

lut_mem

查找表所需内存字节。

不能为空。

输入

rect_lut_id

查找表ID。

不能为空。

输出

参数名称	支持类型	地址对齐	分辨率
lut_mem	-	lut_mem -> phys_addr 16字节对齐。	-

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_dpu_rect.h、ss_mpi_dpu_rect.h
库文件：libss_dpu_rect.a

【注意】

lut_mem -> phys_addr / lut_mem -> virt_addr必须是申请好的内存，lut_mem -> size值为查找表文件大小。

【举例】

无。

【相关主题】

ss_mpi_dpu_rect_unload_lut

ss_mpi_dpu_rect_unload_lut¶

【描述】

卸载查找表。

【语法】

td_s32 ss_mpi_dpu_rect_unload_lut(ot_dpu_rect_lut_id rect_lut_id);

【参数】

参数名称	描述	输入/输出
rect_lut_id	查找表ID。	输入

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_dpu_rect.h、ss_mpi_dpu_rect.h
库文件：libss_dpu_rect.a

【注意】

rect_lut_id 由ss_mpi_dpu_rect_load_lut 获取到。

【举例】

无。

【相关主题】

ss_mpi_dpu_rect_load_lut

ss_mpi_dpu_rect_create_grp¶

【描述】

创建组。

【语法】

td_s32 ss_mpi_dpu_rect_create_grp(ot_dpu_rect_grp  rect_grp, const ot_dpu_rect_grp_attr *grp_attr);

【参数】

参数名称

描述

输入/输出

rect_grp

组号。

取值范围：[0, OT_DPU_RECT_MAX_GRP_NUM)。

输入

grp_attr

组属性。

不能为空。

输入

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_dpu_rect.h、ss_mpi_dpu_rect.h
库文件：libss_dpu_rect.a

【注意】

不支持重复创建。

【举例】

无。

【相关主题】

ss_mpi_dpu_rect_destroy_grp
ss_mpi_dpu_rect_set_grp_attr
ss_mpi_dpu_rect_get_grp_attr
ss_mpi_dpu_rect_start_grp
ss_mpi_dpu_rect_stop_grp

ss_mpi_dpu_rect_destroy_grp¶

【描述】

销毁组。

【语法】

td_s32 ss_mpi_dpu_rect_destroy_grp(ot_dpu_rect_grp rect_grp);

【参数】

参数名称

描述

输入/输出

rect_grp

组号。

取值范围：[0, OT_DPU_RECT_MAX_GRP_NUM)。

输入

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_dpu_rect.h、ss_mpi_dpu_rect.h
库文件：libss_dpu_rect.a

【注意】

组必须已创建。
调用此接口之前，如果已经成功执行ss_mpi_dpu_rect_start_grp，必须先调用ss_mpi_dpu_rect_stop_grp禁用此组。
调用此接口时，会一直等待此组当前任务处理结束才会真正销毁。

【举例】

无。

【相关主题】

ss_mpi_dpu_rect_create_grp
ss_mpi_dpu_rect_set_grp_attr
ss_mpi_dpu_rect_get_grp_attr
ss_mpi_dpu_rect_start_grp
ss_mpi_dpu_rect_stop_grp

ss_mpi_dpu_rect_set_grp_attr¶

【描述】

设置组属性。

【语法】

td_s32 ss_mpi_dpu_rect_set_grp_attr(ot_dpu_rect_grp rect_grp, const ot_dpu_rect_grp_attr *grp_attr);

【参数】

参数名称

描述

输入/输出

rect_grp

组号。

取值范围：[0, OT_DPU_RECT_MAX_GRP_NUM)。

输入

grp_attr

组属性。

不能为空。

输入

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_dpu_rect.h、ss_mpi_dpu_rect.h
库文件：libss_dpu_rect.a

【注意】

组必须已创建。
组属性必须合法，其中部分静态属性不可动态设置，具体请参见ot_dpu_rect_grp_attr。

【举例】

无。

【相关主题】

ss_mpi_dpu_rect_create_grp
ss_mpi_dpu_rect_destroy_grp
ss_mpi_dpu_rect_get_grp_attr
ss_mpi_dpu_rect_start_grp
ss_mpi_dpu_rect_stop_grp

ss_mpi_dpu_rect_get_grp_attr¶

【描述】

获取组属性。

【语法】

td_s32 ss_mpi_dpu_rect_get_grp_attr(ot_dpu_rect_grp rect_grp, ot_dpu_rect_grp_attr *grp_attr);

【参数】

参数名称

描述

输入/输出

rect_grp

组号。

取值范围：[0, OT_DPU_RECT_MAX_GRP_NUM)。

输入

grp_attr

组属性。

不能为空。

输出

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_dpu_rect.h、ss_mpi_dpu_rect.h
库文件：libss_dpu_rect.a

【注意】

组必须已创建。

【举例】

无。

【相关主题】

ss_mpi_dpu_rect_create_grp
ss_mpi_dpu_rect_destroy_grp
ss_mpi_dpu_rect_set_grp_attr
ss_mpi_dpu_rect_start_grp
ss_mpi_dpu_rect_stop_grp

ss_mpi_dpu_rect_start_grp¶

【描述】

启用组。

【语法】

td_s32 ss_mpi_dpu_rect_start_grp(ot_dpu_rect_grp rect_grp);

【参数】

参数名称

描述

输入/输出

rect_grp

组号。

取值范围：[0, OT_DPU_RECT_MAX_GRP_NUM)。

输入

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_dpu_rect.h、ss_mpi_dpu_rect.h
库文件：libss_dpu_rect.a

【注意】

组必须已创建。
组的通道必须先使能。
重复调用该函数设置同一个组返回成功。

【举例】

无。

【相关主题】

ss_mpi_dpu_rect_create_grp
ss_mpi_dpu_rect_destroy_grp
ss_mpi_dpu_rect_set_grp_attr
ss_mpi_dpu_rect_get_grp_attr
ss_mpi_dpu_rect_stop_grp

ss_mpi_dpu_rect_stop_grp¶

【描述】

禁用组。

【语法】

td_s32 ss_mpi_dpu_rect_stop_grp(ot_dpu_rect_grp rect_grp);

【参数】

参数名称

描述

输入/输出

rect_grp

组号。

取值范围：[0, OT_DPU_RECT_MAX_GRP_NUM)。

输入

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_dpu_rect.h、ss_mpi_dpu_rect.h
库文件：libss_dpu_rect.a

【注意】

组必须已创建。
重复禁用同一组返回成功。

【举例】

无。

【相关主题】

ss_mpi_dpu_rect_create_grp
ss_mpi_dpu_rect_destroy_grp
ss_mpi_dpu_rect_set_grp_attr
ss_mpi_dpu_rect_get_grp_attr
ss_mpi_dpu_rect_start_grp

ss_mpi_dpu_rect_set_chn_attr¶

【描述】

设置通道属性。

【语法】

td_s32 ss_mpi_dpu_rect_set_chn_attr(ot_dpu_rect_grp rect_grp, ot_dpu_rect_chn rect_chn, const ot_dpu_rect_chn_attr *chn_attr);

【参数】

参数名称

描述

输入/输出

rect_grp

组号。

取值范围：[0, OT_DPU_RECT_MAX_GRP_NUM)。

输入

rect_chn

通道号。

取值范围：[0, OT_DPU_RECT_MAX_CHN_NUM)。

输入

chn_attr

通道属性。

不能为空。

输入

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_dpu_rect.h、ss_mpi_dpu_rect.h
库文件：libss_dpu_rect.a

【注意】

组必须已创建。

【举例】

无。

【相关主题】

ss_mpi_dpu_rect_get_chn_attr
ss_mpi_dpu_rect_enable_chn
ss_mpi_dpu_rect_disable_chn

ss_mpi_dpu_rect_get_chn_attr¶

【描述】

获取通道属性。

【语法】

td_s32 ss_mpi_dpu_rect_get_chn_attr(ot_dpu_rect_grp rect_grp, ot_dpu_rect_chn rect_chn, ot_dpu_rect_chn_attr *chn_attr);

【参数】

参数名称

描述

输入/输出

rect_grp

组号。

取值范围：[0, OT_DPU_RECT_MAX_GRP_NUM)。

输入

rect_chn

通道号。

取值范围：[0, OT_DPU_RECT_MAX_CHN_NUM)。

输入

chn_attr

通道属性。

不能为空。

输出

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_dpu_rect.h、ss_mpi_dpu_rect.h
库文件：libss_dpu_rect.a

【注意】

组必须已创建。

【举例】

无。

【相关主题】

ss_mpi_dpu_rect_set_chn_attr
ss_mpi_dpu_rect_enable_chn
ss_mpi_dpu_rect_disable_chn

ss_mpi_dpu_rect_enable_chn¶

【描述】

启用通道。

【语法】

td_s32 ss_mpi_dpu_rect_enable_chn(ot_dpu_rect_grp rect_grp, ot_dpu_rect_chn rect_chn);

【参数】

参数名称

描述

输入/输出

rect_grp

组号。

取值范围：[0, OT_DPU_RECT_MAX_GRP_NUM)。

输入

rect_chn

通道号。

取值范围：[0, OT_DPU_RECT_MAX_CHN_NUM)。

输入

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_dpu_rect.h、ss_mpi_dpu_rect.h
库文件：libss_dpu_rect.a

【注意】

组必须已创建。
通道属性必须先设置。
重复使能返回成功。

【举例】

无。

【相关主题】

ss_mpi_dpu_rect_set_chn_attr
ss_mpi_dpu_rect_get_chn_attr
ss_mpi_dpu_rect_disable_chn

ss_mpi_dpu_rect_disable_chn¶

【描述】

禁用通道。

【语法】

td_s32 ss_mpi_dpu_rect_disable_chn(ot_dpu_rect_grp rect_grp, ot_dpu_rect_chn rect_chn);

【参数】

参数名称

描述

输入/输出

rect_grp

组号。

取值范围：[0, OT_DPU_RECT_MAX_GRP_NUM)。

输入

rect_chn

通道号。

取值范围：[0, OT_DPU_RECT_MAX_CHN_NUM)。

输入

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_dpu_rect.h、ss_mpi_dpu_rect.h
库文件：libss_dpu_rect.a

【注意】

组必须已创建。
重复禁用返回成功。

【举例】

无。

【相关主题】

ss_mpi_dpu_rect_set_chn_attr
ss_mpi_dpu_rect_get_chn_attr
ss_mpi_dpu_rect_enable_chn

ss_mpi_dpu_rect_send_frame¶

【描述】

用户发送数据。

【语法】

td_s32 ss_mpi_dpu_rect_send_frame(ot_dpu_rect_grp rect_grp, const ot_video_frame_info *left_frame, const ot_video_frame_info *right_frame, td_s32 milli_sec);

【参数】

参数名称	描述	输入/输出
rect_grp	组号。取值范围：[0, OT_DPU_RECT_MAX_GRP_NUM)。	输入
left_frame	左图图像。不能为空。分辨率大小与组属性中的左图分辨率一致。 ot_video_frame_info请参见《MPP 媒体处理软件 V5.0 开发参考》“系统控制”章节。	输入
right_frame	右图图像。当组属性设置OT_DPU_RECT_MODE_DOUBL时，不能为空。分辨率大小与组属性中的右图分辨率一致。 ot_video_frame_info请参见《MPP 媒体处理软件 V5.0 开发参考》“系统控制”章节。	输入
milli_sec	超时参数 milli_sec 设为-1 时，为阻塞接口；0 时为非阻塞接口；大于 0 时为超时等待时间，超时时间的单位为毫秒（ms）。	输入
left_frame	图像像素格式：OT_PIXEL_FORMAT_YVU_SEMIPLANAR_420/OT_PIXEL_FORMAT_YVU_SEMIPLANAR_422/OT_PIXEL_FORMAT_YUV_400 图像格式：OT_VIDEO_FORMAT_LINEAR 视频压缩模式：OT_COMPRESS_MODE_NONE 动态范围：OT_DYNAMIC_RANGE_SDR8 帧场模式：OT_VIDEO_FIELD_FRAME	16 byte 128x64～2048x2048
right_frame	图像像素格式： OT_PIXEL_FORMAT_YVU_SEMIPLANAR_420/OT_PIXEL_FORMAT_YVU_SEMIPLANAR_422/OT_PIXEL_FORMAT_YUV_400 图像格式：OT_VIDEO_FORMAT_LINEAR 视频压缩模式：OT_COMPRESS_MODE_NONE 动态范围：OT_DYNAMIC_RANGE_SDR8 帧场模式：OT_VIDEO_FIELD_FRAME	16 byte 128x64～2048x2048

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_dpu_rect.h、ss_mpi_dpu_rect.h
库文件：libss_dpu_rect.a

【注意】

组必须已创建。
用户使用此接口时，可以自行进行帧率控制。
left_frame / right_frame 图像地址必须是VB申请的，宽高要求2对齐，stride要求16字节对齐。

【举例】

无。

【相关主题】

ss_mpi_dpu_rect_get_frame
ss_mpi_dpu_rect_release_frame

ss_mpi_dpu_rect_get_frame¶

【描述】

用户从通道获取一帧处理完成的图像。

【语法】

td_s32 ss_mpi_dpu_rect_get_frame(ot_dpu_rect_grp rect_grp, td_s32 milli_sec, ot_dpu_rect_frame_info *rect_frame_info);

【参数】

参数名称

描述

输入/输出

rect_grp

组号。

取值范围：[0, OT_DPU_RECT_MAX_GRP_NUM)。

输入

rect_frame_info

校正图像帧信息。

包含原始图像和校正之后的图像。

输出

milli_sec

超时参数 milli_sec 设为-1 时，为阻塞接口；0 时为非阻塞接口；大于 0 时为超时等待时间，超时时间的单位为毫秒（ms）。

输入

参数名称

支持类型

地址对齐

分辨率

rect_frame_info

原始图像支持：OT_PIXEL_FORMAT_YVU_SEMIPLANAR_420/OT_PIXEL_FORMAT_YVU_SEMIPLANAR_422/OT_PIXEL_FORMAT_YUV_400

16 byte

128x64～2048x2048

校正之后图像支持：

PIXEL_FORMAT_YUV_400

16 byte

128x64～1920x1080

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_dpu_rect.h、ss_mpi_dpu_rect.h
库文件：libss_dpu_rect.a

【注意】

组必须已创建。
只有设置组属性的队列深度不为0，才能获取到图像。
若是用户发送数据模式，原始图像数据信息由用户保证，若是绑定模式，由系统保证。
校正之后的图像数据信息由系统保证。

【举例】

无。

【相关主题】

ss_mpi_dpu_rect_send_frame
ss_mpi_dpu_rect_release_frame

ss_mpi_dpu_rect_release_frame¶

【描述】

用户释放帧通道图像。

【语法】

td_s32 ss_mpi_dpu_rect_release_frame(ot_dpu_rect_grp rect_grp, const ot_dpu_rect_frame_info *rect_frame_info);

【参数】

参数名称

描述

输入/输出

rect_grp

组号。

取值范围：[0, OT_DPU_RECT_MAX_GRP_NUM)。

输入

rect_frame_info

校正图像帧信息。

包含原始图像和校正之后的图像。

输入

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_dpu_rect.h、ss_mpi_dpu_rect.h
库文件：libss_dpu_rect.a

【注意】

组必须已创建。
rect_frame_info由ss_mpi_dpu_rect_get_frame获取，与其配对使用。

【举例】

无。

【相关主题】

ss_mpi_dpu_rect_send_frame
ss_mpi_dpu_rect_get_frame

数据类型和数据结构¶

DPU_RECT相关数据类型、数据结构定义如下：

ot_dpu_rect_lut_id：定义查找表ID。
ot_dpu_rect_grp：定义组号。
ot_dpu_rect_pipe：定义管道号。
ot_dpu_rect_chn：定义通道号。
ot_dpu_rect_mode：定义校正模式。
ot_dpu_rect_grp_attr：定义组属性。
ot_dpu_rect_chn_attr：定义通道属性。
ot_dpu_rect_mem_info：定义一维内存信息。
ot_dpu_rect_frame_info：定义校正图像帧信息。
OT_DPU_RECT_MAX_GRP_NUM：定义最大组数。
OT_DPU_RECT_MAX_PIPE_NUM：定义最大管道数。
OT_DPU_RECT_MAX_CHN_NUM：定义最大通道数。
OT_DPU_RECT_IN_IMAGE_MAX_WIDTH：定义最大输入图像的宽度。
OT_DPU_RECT_IN_IMAGE_MAX_HEIGHT：定义最大输入图像的高度。
OT_DPU_RECT_IN_IMAGE_MIN_WIDTH：定义最小输入图像的宽度。
OT_DPU_RECT_IN_IMAGE_MIN_HEIGHT：定义最小输入图像的高度。
OT_DPU_RECT_OUT_IMAGE_MAX_WIDTH：定义最大输出图像的宽度。
OT_DPU_RECT_OUT_IMAGE_MAX_HEIGHT：定义最大输出图像的高度。
OT_DPU_RECT_OUT_IMAGE_MIN_WIDTH：定义最小输出图像的宽度。
OT_DPU_RECT_OUT_IMAGE_MIN_HEIGHT：定义最小输出图像的高度。

ot_dpu_rect_lut_id¶

【说明】

定义查找表ID。

【定义】

typedef td_s32  ot_dpu_rect_lut_id;

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

无。

ot_dpu_rect_grp¶

【说明】

定义组号。

【定义】

typedef td_s32 ot_dpu_rect_grp;

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

无。

ot_dpu_rect_pipe¶

【说明】

定义管道号。

【定义】

typedef td_s32 ot_dpu_rect_pipe;

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

无。

ot_dpu_rect_chn¶

【说明】

定义通道号。

【定义】

typedef td_s32 ot_dpu_rect_chn;

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

无。

ot_dpu_rect_mode¶

【说明】

定义校正模式。

【定义】

typedef enum {
    OT_DPU_RECT_MODE_SINGLE = 0x0, /* only channel 0 work */
    OT_DPU_RECT_MODE_DOUBLE = 0x1, /* two channel work */
    OT_DPU_RECT_MODE_BUTT
} ot_dpu_rect_mode;

【成员】

成员名称	描述
OT_DPU_RECT_MODE_SINGLE	单通道校正。
OT_DPU_RECT_MODE_DOUBLE	双通道校正。

【注意事项】

无。

【相关数据类型及接口】

无。

ot_dpu_rect_grp_attr¶

【说明】

定义组属性。

【定义】

typedef struct {
    ot_dpu_rect_mode rect_mode; /* rectification mode, it can not be changed dynamic */
    ot_size left_image_size; /* left image size. */
    ot_size right_image_size; /* right image size. */
    ot_dpu_rect_lut_id left_lut_id; /* left image rectification lut */
    ot_dpu_rect_lut_id right_lut_id; /* right image rectification lut */
    td_u32 depth; /* the depth of user image queue for getting rectification output image,
                      * it can not be changed dynamic. range:[0,8]
                      */
    td_bool is_need_src_frame; /* the flag of getting source videoframe. */
    ot_frame_rate_ctrl frame_rate; /* grp frame rate contrl. */
} ot_dpu_rect_grp_attr;

【成员】

成员名称	描述
rect_mode	校正模式，静态属性，不可动态更改。
left_image_size	左图分辨率。取值范围：宽[128, 2048]; 高[64, 2048]。 ot_size请参见《MPP 媒体处理软件 V5.0 开发参考》“系统控制”章节。
right_image_size	右图分辨率。取值范围：宽[128, 2048]; 高[64, 2048]。 ot_size请参见《MPP 媒体处理软件 V5.0 开发参考》“系统控制”章节。
left_lut_id	左图查找表ID。有效范围: [0, 32)。
right_lut_id	右图查找表ID。有效范围: [0, 32)。
depth	通道图像的队列长度，静态属性，不可动态更改。取值范围: [0, 8]。
is_need_src_frame	是否需要获取原始图像帧标志。
frame_rate	组帧率。源帧率(src_frame_rate) 取值范围：-1 或[1, 240]；目的帧率(dst_frame_rate) 取值范围：[1, src_frame_rate] 或 -1（仅在src_frame_rate为-1时，目的帧率才能取值为-1）。 ot_frame_rate_ctrl请参见《MPP 媒体处理软件 V5.0 开发参考》“系统控制”章节。

【注意事项】

分辨率宽、高要求偶数对齐。

【相关数据类型及接口】

无。

ot_dpu_rect_chn_attr¶

【说明】

定义通道属性。

【定义】

typedef struct {
    ot_size image_size; /* rectification output image size */
} ot_dpu_rect_chn_attr;

【成员】

成员名称

描述

image_size

目标分辨率。取值范围: 宽[128, 1920]; 高[64, 1080]。

ot_size请参见《MPP 媒体处理软件 V5.0 开发参考》“系统控制”章节。

【注意事项】

分辨率宽、高要求偶数对齐。
目标分辨率与查找表分辨率一致。
目标分辨率必须小于等于输入图像分辨率。

【相关数据类型及接口】

无。

ot_dpu_rect_mem_info¶

【说明】

定义一维内存信息。

【定义】

typedef struct {
    td_u64 phys_addr;
    td_u64 virt_addr;
    td_u32 size;
} ot_dpu_rect_mem_info;

【成员】

成员名称	描述
phys_addr	内存块物理地址。
virt_addr	内存块虚拟地址。
size	内存块字节数，见图1。

【注意事项】

无。

【相关数据类型及接口】

无。

ot_dpu_rect_frame_info¶

【说明】

定义校正图像帧信息。

【定义】

typedef struct {
    ot_video_frame_info src_frame[OT_DPU_RECT_MAX_PIPE_NUM]; /* src_frame[0]:left   frame,src_frame[1]:right frame */
   ot_video_frame_info rect_frame[OT_DPU_RECT_MAX_PIPE_NUM]; /* rect_frame[0]:left frame,rect_frame[1]:right frame */
} ot_dpu_rect_frame_info;

【成员】

成员名称

描述

src_frame[OT_DPU_RECT_MAX_PIPE_NUM]

左右原始图像帧。

ot_video_frame_info请参见《MPP 媒体处理软件 V5.0 开发参考》“系统控制”章节

rect_frame[OT_DPU_RECT_MAX_PIPE_NUM]

左右校正图像帧。

ot_video_frame_info请参见《MPP 媒体处理软件 V5.0 开发参考》“系统控制”章节

【注意事项】

无。

【相关数据类型及接口】

无。

OT_DPU_RECT_MAX_GRP_NUM¶

【说明】

定义最大组数。

【定义】

#define OT_DPU_RECT_MAX_GRP_NUM           16

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

无。

OT_DPU_RECT_MAX_PIPE_NUM¶

【说明】

定义最大管道数。

【定义】

#define OT_DPU_RECT_MAX_PIPE_NUM          2

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

无。

OT_DPU_RECT_MAX_CHN_NUM¶

【说明】

定义最大管道数。

【定义】

#define OT_DPU_RECT_MAX_CHN_NUM          2

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

无。

OT_DPU_RECT_IN_IMAGE_MAX_WIDTH¶

【说明】

定义最大输入图像的宽度。

【定义】

#define OT_DPU_RECT_IN_IMAGE_MAX_WIDTH    2048

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

无。

OT_DPU_RECT_IN_IMAGE_MAX_HEIGHT¶

【说明】

定义最大输入图像的高度。

【定义】

#define OT_DPU_RECT_IN_IMAGE_MAX_HEIGHT   2048

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

无。

OT_DPU_RECT_IN_IMAGE_MIN_WIDTH¶

【说明】

定义最小输入图像的宽度。

【定义】

#define OT_DPU_RECT_IN_IMAGE_MIN_WIDTH    128

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

无。

OT_DPU_RECT_IN_IMAGE_MIN_HEIGHT¶

【说明】

定义最小输入图像的高度。

【定义】

#define OT_DPU_RECT_IN_IMAGE_MIN_HEIGHT   64

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

无。

OT_DPU_RECT_OUT_IMAGE_MAX_WIDTH¶

【说明】

定义最大输出图像的宽度。

【定义】

#define OT_DPU_RECT_OUT_IMAGE_MAX_WIDTH   1920

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

无。

OT_DPU_RECT_OUT_IMAGE_MAX_HEIGHT¶

【说明】

定义最大输出图像的高度。

【定义】

#define OT_DPU_RECT_OUT_IMAGE_MAX_HEIGHT  1080

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

无。

OT_DPU_RECT_OUT_IMAGE_MIN_WIDTH¶

【说明】

定义最小输出图像的宽度。

【定义】

#define OT_DPU_RECT_OUT_IMAGE_MIN_WIDTH   128

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

无。

OT_DPU_RECT_OUT_IMAGE_MIN_HEIGHT¶

【说明】

定义最小输出图像的高度。

【定义】

#define OT_DPU_RECT_OUT_IMAGE_MIN_HEIGHT  64

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

无。

错误码¶

本模块API错误码如下所示。

表 1 DPU_RECT模块API错误码

错误代码	宏定义	描述
0xa0358001	OT_ERR_DPU_RECT_INVALID_DEV_ID	设备ID超出合法范围
0xa0358003	OT_ERR_DPU_RECT_INVALID_CHN_ID	通道号错误或无效区域句柄
0xa0358005	OT_ERR_DPU_RECT_INVALID_GRP_ID	组号错误或无效区域句柄
0xa0358007	OT_ERR_DPU_RECT_ILLEGAL_PARAM	参数超出合法范围
0xa0358008	OT_ERR_DPU_RECT_EXIST	重复创建已存在的设备、通道或资源
0xa0358009	OT_ERR_DPU_RECT_UNEXIST	试图使用或者销毁不存在的设备、通道或者资源
0xa035800a	OT_ERR_DPU_RECT_NULL_PTR	函数参数中有空指针
0xa035800c	OT_ERR_DPU_RECT_NOT_SUPPORT	不支持的参数或者功能
0xa035800d	OT_ERR_DPU_RECT_NOT_PERM	该操作不允许，如试图修改静态配置参数
0xa0358014	OT_ERR_DPU_RECT_NO_MEM	分配内存失败，如系统内存不足
0xa0358015	OT_ERR_DPU_RECT_NO_BUF	分配缓存失败，如申请的图像缓冲区太大
0xa0358016	OT_ERR_DPU_RECT_BUF_EMPTY	缓冲区中无图像
0xa0358018	OT_ERR_DPU_RECT_NOT_READY	系统没有初始化或没有加载相应模块
0xa0358022	OT_ERR_DPU_RECT_BUSY	系统忙
0xa0358040	OT_ERR_DPU_RECT_SYS_TIMEOUT	系统超时
0xa0358041	OT_ERR_DPU_RECT_OPEN_FILE	打开文件失败
0xa0358042	OT_ERR_DPU_RECT_READ_FILE	读文件失败
0xa0358043	OT_ERR_DPU_RECT_WRITE_FILE	写文件失败

Proc调试信息¶

概述¶

调试信息采用了Linux下的proc文件系统，可实时反映当前系统的运行状态，所记录的信息可供问题定位及分析时使用。

【文件目录】

/proc/umap

【信息查看方法】

在控制台上可以使用cat命令查看信息，cat /proc/umap/rect；也可以使用其他常用的文件操作命令，例如 cp /proc/umap/rect ./，将文件拷贝到当前目录。
在应用程序中可以将上述文件当作普通只读文件进行读操作，例如fopen、fread等。

说明： 参数在描述时有以下2种情况需要注意：

取值为{0, 1}的参数，如未列出具体取值和含义的对应关系，则参数为1时表示肯定，为0时表示否定。

取值为{aaa, bbb, ccc}的参数，未列出具体取值和含义的对应关系，但可直接根据取值aaa、bbb或ccc判断参数含义

Proc信息说明¶

【调试信息】

# cat /proc/umap/rect
[DPU_RECT] Version: [Vx.x.x.x B0xx Release], Build Time[mm  dd yyyy, hh:mm:ss]
----------------------------------------dpu rect hardware status-------------------------------------------
  is_busy    timeout_cnt
         n                0
----------------------------------------dpu rect grp attr1---------------------------------------------------
grp_id    mode  is_start   grp_state  is_need_src_frame  depth  src_frame_rate  dst_frame_rate
       0  double         y      create                  y      0              -1              -1
----------------------------------------dpu rect grp attr2---------------------------------------------------
  left_width  left_height  right_width  right_height
        1280          720         1280           720
----------------------------------------dpu rect chn attr----------------------------------------------------
  grp_id  chn_id  enable  width  height
       0       0       y   1280     720
       0       1       y   1280     720
----------------------------------------dpu rect lut attr-----------------------------------------------------
  grp_id  chn_id  lut_id  phys_addr   width  height
       0       0       0   727a6010    1280     720
       0       1       1   72b2b010    1280     720
----------------------------------------dpu rect pipe queue------------------------------------------------
  grp_id  pipe_id  busy_num  free_num
       0        0         0         8
       0        1         0         8
----------------------------------------dpu rect out queue--------------------------------------------------
  grp_id  busy_num  free_num
       0         1         0
----------------------------------------dpu rect work queue------------------------------------------------
  busy_num  free_num
         0       128
----------------------------------------dpu rect grp status--------------------------------------------------
  grp_id  frame_rate  start_cnt  start_fail_cnt  send_pic_cnt  frame_lost
       0           1          1               0             1           0
  grp_id  pipe_id  in_frame_lost
       0        0              0
       0        1              0
----------------------------------------dpu rect run-time info1--------------------------------------------
  irq_num_per_sec  max_irq_num_per_sec  irq_num_last_sec  irq_num_cur  cur_irq_cost_time  max_irq_cost_time
     31               31              466          481            56           67
 
----------------------------------------dpu rect run-time info2--------------------------------------------
irq_cost_per_sec  max_irq_cost_per_sec  irq_time_total  proc_cost_per_frame  hw_proc_cost_per_frame     runtime
  1780                 1916           28123                 3908                    3889          17

【调试信息分析】

记录当前DPU_RECT属性配置以及状态信息。

【参数说明】

参数		描述
dpu rect hardware status DPU RECT 硬件工作状态信息	is_usy	DPU RECT 硬件是否忙。 y: 硬件忙; n: 硬件空闲。
dpu rect hardware status DPU RECT 硬件工作状态信息	timeout_cnt	DPU RECT 系统超时次数。
dpu rect grp attr DPU RECT 组属性信息。	grp_id	组ID号。有效范围：[0, 16)。
	mode	校正处理模式。有效范围见枚举ot_dpu_rect_mode。
	is_start	组启动状态。 y:启动; n:未启动。
	grp_state	组工作状态。 create:创建; destroying:销毁。
	is_need_src_frame	是否需要获取原始图像标志。 y: 需要获取原始图像； n: 不需要获取原始图像。
	depth	输出队列深度。取值范围: [0, 8]。
	src_frame_rate	组源帧率
	dst_frame_rate	组目标帧率
	left_width	输入左图分辨率的宽。取值范围：[128, 2048]。
	left_height	输入左图分辨率的高。取值范围：[64, 2048]。
	right_width	输入右图分辨率的宽。取值范围：[128, 2048]。
	right_height	输入右图分辨率的高。取值范围：[64, 2048]。
dpu rect chn attr DPU RECT通道属性信息	grp_id	组ID号。有效范围：[0, 16)。
	chn_id	通道ID号。有效范围：[0, 2)。
	enable	通道使能标志。 y:使能; n:未使能。
	width	通道输出的目标图像分辨率的宽。取值范围: [128, 1920]。
	height	通道输出的目标图像分辨率的高。取值范围: [64, 1080]。
dpu rect lut attr DPU RECT 查找表属性	grp_id	组ID号。有效范围: [0, 16)。
	chn_id	通道ID号。有效范围: [0, 2)。
	lut_id	查找表ID号。有效范围: [0, 32)。
	phys_addr	查找表物理地址。
	width	查找表分辨率的宽。与通道输出的目标图像分辨率的宽一致。取值范围: [128, 1920]。
	height	查找表分辨率的高。与通道输出的目标图像分辨率的高一致。取值范围: [64, 1080]。
dpu rect pipe queue DPU RECT 输入管道队列信息	grp_id	组ID号。有效范围：[0, 16)。
	pipe_id	管道ID号。有效范围：[0, 2)。
	busy_num	已用节点数。
	free_num	可用节点数。
dpu rect out queue DPU RECT 输出通道队列信息	grp_id	GRP ID号。有效范围：[0, 16)。
	busy_num	已用节点数。
	free_num	可用节点数。
dpu rect work queue DPU RECT 工作队列信息	busy_num	已用节点数。
dpu rect work queue DPU RECT 工作队列信息	free_num	可用节点数。
dpu rect grp status DPU RECT 组状态信息	grp_id	组ID号。有效范围：[0, 16)。
	frame_rate	输出帧率。
	start_cnt	任务启动次数。
	start_fail_cnt	任务启动失败次数。
	send_pic_cnt	发图像成功次数。
	frame_lost	因队列满丢失的输出图像数
	CurTaskCostTm	当前完成任务的耗时。
	MaxTaskCostTm	历史上耗时最长任务的执行时间。
	grp_id	组ID号。有效范围：[0, 16)。
	pipe_id	PIPE ID号。有效范围：[0, 2)。
	in_frame_lost	因队列满丢失的输入图像数。
dpu rect run-time info DPU RECT运行时相关信息	irq_num_per_sec	最近一次的1秒内中断执行次数。
	max_irq_num_per_sec	历史上的1秒内最大的中断执行次数。
	irq_num_last_sec	上一秒上报中断总次数。
	irq_num_cur	DPU RECT产生中断的总次数。
	cur_irq_cost_time	最近一次执行中断的执行耗时。单位：us
	max_irq_cost_time	执行一次中断的最大耗时。单位：us
	irq_cost_per_sec	最近一秒执行中断的执行耗时。单位：us
	max_irq_cost_per_sec	历史上一秒执行中断的最大执行耗时。单位：us
	irq_time_total	中断处理总时间。单位：us
	proc_cost_per_frame	单帧图像处理的总时间。单位：us
	hw_proc_cost_per_frame	单帧图像处理的硬件时间。单位：us
	runtime	DPU RECT运行总时间。单位：s

DPU_MATCH¶

概述¶

DPU(Depth Process Unit)为_识别_分析系统中的深度处理单元。用户基于DPU对输入的左图像和右图像经过校正和匹配计算得出深度图。DPU分为校正(DPU_RECT)和匹配(DPU_MATCH)两个模块，同时使用，也可单独使用。DPU_MATCH对输入的左图像和右图像进行匹配处理输出深度图。

功能描述¶

重要概念¶

组(GROUP)

DPU_MATCH 对用户提供组（GROUP）的概念。最大可用数为 16 个，各组分时复用 DPU_MATCH硬件。
通道(CHANNEL )

DPU_MATCH组的通道。每组包含单个通道。
管道(PIPE)

DPU_MATCH组的管道。每组包含两个管道，分为左右两管道
ot_dpu_match_mem_info内存排布

图 1 ot_dpu_match_mem_info数据内存示意

调用流程¶

支持DPU_RECT作为DPU_MATCH的源。目前无目标模块可以绑定DPU_MATCH, 接收DPU_MATCH进行处理，必须手动的调用ss_mpi_dpu_match_get_frame获取结果，再进行处理。如图1所示。

图 1 DPU_MATCH调用流程

API参考¶

该功能模块为用户提供以下MPI：

ss_mpi_dpu_match_get_assist_buf_size：获取辅助内存字节数。
ss_mpi_dpu_match_create_grp：创建组。
ss_mpi_dpu_match_destroy_grp：销毁组。
ss_mpi_dpu_match_set_grp_attr：设置组属性。
ss_mpi_dpu_match_get_grp_attr：获取组属性。
ss_mpi_dpu_match_start_grp：启用组。
ss_mpi_dpu_match_stop_grp：禁用组。
ss_mpi_dpu_match_set_chn_attr：设置通道属性。
ss_mpi_dpu_match_get_chn_attr：获取通道属性。
ss_mpi_dpu_match_enable_chn：启用通道。
ss_mpi_dpu_match_disable_chn：禁用通道。
ss_mpi_dpu_match_send_frame：用户发送数据。
ss_mpi_dpu_match_get_frame：用户从通道获取一帧处理完成的图像。
ss_mpi_dpu_match_release_frame：用户释放一帧通道图像。
ss_mpi_dpu_match_set_grp_cost_param：设置组的代价参数。
ss_mpi_dpu_match_get_grp_cost_param：获取组的代价参数。
ss_mpi_dpu_match_set_grp_param：设置组参数。
ss_mpi_dpu_match_get_grp_param：获取组参数。

ss_mpi_dpu_match_get_assist_buf_size¶

【描述】

获取辅助内存字节数。

【语法】

td_s32 ss_mpi_dpu_match_get_assist_buf_size(td_u16 disparity_num, td_u32 dst_height, td_u32 *size);

【参数】

参数名称

描述

输入/输出

disparity_num

视差值数目。

取值范围：[16, 224]，必须为16的倍数。

输入

dst_height

输出的图像高。

输入

size

辅助内存字节数。

不能为空。

输出

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_dpu_match.h、ss_mpi_dpu_match.h
库文件：libss_dpu_match.a

【注意】

无。

【举例】

无。

【相关主题】

ss_mpi_dpu_match_create_grp

ss_mpi_dpu_match_create_grp¶

【描述】

创建组。

【语法】

td_s32 ss_mpi_dpu_match_create_grp(ot_dpu_match_grp match_grp, const ot_dpu_match_grp_attr *grp_attr);

【参数】

参数名称

描述

输入/输出

match_grp

组号。

取值范围：[0, OT_DPU_MATCH_MAX_GRP_NUM)。

输入

grp_attr

组属性。

不能为空。

输入

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_dpu_match.h、ss_mpi_dpu_match.h
库文件：libss_dpu_match.a

【注意】

不支持重复创建。

【举例】

无。

【相关主题】

ss_mpi_dpu_match_destroy_grp
ss_mpi_dpu_match_set_grp_attr
ss_mpi_dpu_match_get_grp_attr
ss_mpi_dpu_match_start_grp
ss_mpi_dpu_match_stop_grp

ss_mpi_dpu_match_destroy_grp¶

【描述】

销毁组。

【语法】

td_s32 ss_mpi_dpu_match_destroy_grp(ot_dpu_match_grp match_grp);

【参数】

参数名称

描述

输入/输出

match_grp

组号。

取值范围：[0, OT_DPU_MATCH_MAX_GRP_NUM)。

输入

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_dpu_match.h、ss_mpi_dpu_match.h
库文件：libss_dpu_match.a

【注意】

组必须已创建。
调用此接口之前，如果已经成功执行ss_mpi_dpu_match_start_grp，必须先调用ss_mpi_dpu_match_stop_grp禁用此组。
调用此接口时，会一直等待此组当前任务处理结束才会真正销毁。

【举例】

无。

【相关主题】

ss_mpi_dpu_match_create_grp
ss_mpi_dpu_match_set_grp_attr
ss_mpi_dpu_match_get_grp_attr
ss_mpi_dpu_match_start_grp
ss_mpi_dpu_match_stop_grp

ss_mpi_dpu_match_set_grp_attr¶

【描述】

设置组属性。

【语法】

td_s32 ss_mpi_dpu_match_set_grp_attr(ot_dpu_match_grp match_grp, const ot_dpu_match_grp_attr *grp_attr);

【参数】

参数名称

描述

输入/输出

match_grp

组号。

取值范围：[0, OT_DPU_MATCH_MAX_GRP_NUM)。

输入

grp_attr

组属性。

不能为空。

输入

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_dpu_match.h、ss_mpi_dpu_match.h
库文件：libss_dpu_match.a

【注意】

组必须已创建。
组属性必须合法，其中部分静态属性不可动态设置，具体请参见ot_dpu_match_grp_attr。

【举例】

无。

【相关主题】

ss_mpi_dpu_match_create_grp
ss_mpi_dpu_match_destroy_grp
ss_mpi_dpu_match_get_grp_attr
ss_mpi_dpu_match_start_grp
ss_mpi_dpu_match_stop_grp

ss_mpi_dpu_match_get_grp_attr¶

【描述】

获取组属性。

【语法】

td_s32 ss_mpi_dpu_match_get_grp_attr(ot_dpu_match_grp match_grp, ot_dpu_match_grp_attr *grp_attr);

【参数】

参数名称

描述

输入/输出

match_grp

组号。

取值范围：[0, OT_DPU_MATCH_MAX_GRP_NUM)。

输入

grp_attr

组属性。

不能为空。

输出

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_dpu_match.h、ss_mpi_dpu_match.h
库文件：libss_dpu_match.a

【注意】

组必须已创建。

【举例】

无。

【相关主题】

ss_mpi_dpu_match_create_grp
ss_mpi_dpu_match_destroy_grp
ss_mpi_dpu_match_set_grp_attr
ss_mpi_dpu_match_start_grp
ss_mpi_dpu_match_stop_grp

ss_mpi_dpu_match_start_grp¶

【描述】

启用组。

【语法】

td_s32 ss_mpi_dpu_match_start_grp(ot_dpu_match_grp match_grp);

【参数】

参数名称

描述

输入/输出

match_grp

组号。

取值范围：[0, OT_DPU_MATCH_MAX_GRP_NUM)。

输入

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_dpu_match.h、ss_mpi_dpu_match.h
库文件：libss_dpu_match.a

【注意】

组必须已创建。
组的通道必须先使能。
重复调用该函数设置同一个组返回成功。

【举例】

无。

【相关主题】

ss_mpi_dpu_match_create_grp
ss_mpi_dpu_match_destroy_grp
ss_mpi_dpu_match_set_grp_attr
ss_mpi_dpu_match_get_grp_attr
ss_mpi_dpu_match_stop_grp

ss_mpi_dpu_match_stop_grp¶

【描述】

禁用组。

【语法】

td_s32 ss_mpi_dpu_match_stop_grp(ot_dpu_match_grp match_grp);

【参数】

参数名称

描述

输入/输出

match_grp

组号。

取值范围：[0, OT_DPU_MATCH_MAX_GRP_NUM)。

输入

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_dpu_match.h、ss_mpi_dpu_match.h
库文件：libss_dpu_match.a

【注意】

组必须已创建。
重复禁用同一组返回成功。

【举例】

无。

【相关主题】

ss_mpi_dpu_match_create_grp
ss_mpi_dpu_match_destroy_grp
ss_mpi_dpu_match_set_grp_attr
ss_mpi_dpu_match_get_grp_attr
ss_mpi_dpu_match_start_grp

ss_mpi_dpu_match_set_chn_attr¶

【描述】

设置通道属性。

【语法】

td_s32 ss_mpi_dpu_match_set_chn_attr(ot_dpu_match_grp match_grp, ot_dpu_match_chn match_chn, const ot_dpu_match_chn_attr *chn_attr);

【参数】

参数名称

描述

输入/输出

match_grp

组号。

取值范围：[0, OT_DPU_MATCH_MAX_GRP_NUM)。

输入

match_chn

通道号。

取值范围：[0,1)。

输入

chn_attr

通道属性。

不能为空。

输入

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_dpu_match.h、ss_mpi_dpu_match.h
库文件：libss_dpu_match.a

【注意】

组必须已创建。

【举例】

无。

【相关主题】

ss_mpi_dpu_match_get_chn_attr
ss_mpi_dpu_match_enable_chn
ss_mpi_dpu_match_disable_chn

ss_mpi_dpu_match_get_chn_attr¶

【描述】

获取通道属性。

【语法】

td_s32 ss_mpi_dpu_match_get_chn_attr(ot_dpu_match_grp match_grp, ot_dpu_match_chn match_chn, ot_dpu_match_chn_attr *chn_attr);

【参数】

参数名称

描述

输入/输出

match_grp

组号。

取值范围：[0, OT_DPU_MATCH_MAX_GRP_NUM)。

输入

match_chn

通道号。

取值范围：[0,1)。

输入

chn_attr

通道属性。

不能为空。

输出

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_dpu_match.h、ss_mpi_dpu_match.h
库文件：libss_dpu_match.a

【注意】

组必须已创建。

【举例】

无。

【相关主题】

ss_mpi_dpu_match_set_chn_attr
ss_mpi_dpu_match_enable_chn
ss_mpi_dpu_match_disable_chn

ss_mpi_dpu_match_enable_chn¶

【描述】

启用通道。

【语法】

td_s32 ss_mpi_dpu_match_enable_chn(ot_dpu_match_grp match_grp, ot_dpu_match_chn match_chn);

【参数】

参数名称

描述

输入/输出

match_grp

组号。

取值范围：[0, OT_DPU_MATCH_MAX_GRP_NUM)。

输入

match_chn

通道号。

取值范围：[0,1)。

输入

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_dpu_match.h、ss_mpi_dpu_match.h
库文件：libss_dpu_match.a

【注意】

组必须已创建。
通道属性必须先设置。
重复使能返回成功。

【举例】

无。

【相关主题】

ss_mpi_dpu_match_set_chn_attr
ss_mpi_dpu_match_get_chn_attr
ss_mpi_dpu_match_disable_chn

ss_mpi_dpu_match_disable_chn¶

【描述】

禁用通道。

【语法】

td_s32 ss_mpi_dpu_match_disable_chn(ot_dpu_match_grp match_grp, ot_dpu_match_chn match_chn);

【参数】

参数名称

描述

输入/输出

match_grp

组号。

取值范围：[0, OT_DPU_MATCH_MAX_GRP_NUM)。

输入

match_chn

通道号。

取值范围：[0,1)。

输入

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_dpu_match.h、ss_mpi_dpu_match.h
库文件：libss_dpu_match.a

【注意】

组必须已创建。
重复禁用返回成功。

【举例】

无。

【相关主题】

ss_mpi_dpu_match_set_chn_attr
ss_mpi_dpu_match_get_chn_attr
ss_mpi_dpu_match_enable_chn

ss_mpi_dpu_match_send_frame¶

【描述】

用户发送数据。

【语法】

td_s32 ss_mpi_dpu_match_send_frame(ot_dpu_match_grp match_grp, const ot_dpu_match_frame_info *src_frame_info, td_s32 milli_sec);

【参数】

参数名称

描述

输入/输出

match_grp

组号。

取值范围：[0, OT_DPU_MATCH_MAX_GRP_NUM)。

输入

src_frame_info

匹配原始图像帧信息。

其中校正左右图像的分辨率大小分别与组属性中的左右图分辨率一致。

不能为空。

输入

milli_sec

超时参数 milli_sec 设为-1 时，为阻塞接口；0 时为非阻塞接口；大于 0 时为超时等待时间，超时时间的单位为毫秒（ms）。

输入

参数名称

支持类型

地址对齐

分辨率

src_frame_info

原始图像支持图像像素格式：

OT_PIXEL_FORMAT_YVU_SEMIPLANAR_420/OT_PIXEL_FORMAT_YVU_SEMIPLANAR_422/OT_PIXEL_FORMAT_YUV_400

图像格式：OT_VIDEO_FORMAT_LINEAR

视频压缩模式：OT_COMPRESS_MODE_NONE

动态范围：OT_DYNAMIC_RANGE_SDR8

帧场模式：OT_VIDEO_FIELD_FRAME

16 byte

128x64～2048x2048

校正图像支持：OT_PIXEL_FORMAT_YVU_SEMIPLANAR_420/OT_PIXEL_FORMAT_YVU_SEMIPLANAR_422/OT_PIXEL_FORMAT_YUV_400

图像格式：OT_VIDEO_FORMAT_LINEAR

视频压缩模式：OT_COMPRESS_MODE_NONE

动态范围：OT_DYNAMIC_RANGE_SDR8

帧场模式：OT_VIDEO_FIELD_FRAME

16 byte

128x64～1920x1080

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_dpu_match.h、ss_mpi_dpu_match.h
库文件：libss_dpu_match.a

【注意】

组必须已创建。
用户使用此接口时，可以自行进行帧率控制。
src_frame_info 里面的src_frame, rect_frame图像地址必须是VB申请的，宽高要求2对齐，stride要求16字节对齐。
匹配模块对于src_frame_info 里面的src_frame只是用于保证ss_mpi_dpu_match_get_frame获取到的原始图像，校正图像和匹配图像是一致的，不会对src_frame做任何处理，因此只检查VB合法性，不检查图像参数。

【举例】

无。

【相关主题】

ss_mpi_dpu_match_get_frame
ss_mpi_dpu_match_release_frame

ss_mpi_dpu_match_get_frame¶

【描述】

用户从通道获取处理完成的图像。

【语法】

td_s32 ss_mpi_dpu_match_get_frame(ot_dpu_match_grp match_grp, td_s32 milli_sec, ot_dpu_match_frame_info *src_frame_info, ot_video_frame_info *dst_frame);

【参数】

参数名称	描述	输入/输出
match_grp	组号。取值范围：[0, OT_DPU_MATCH_MAX_GRP_NUM)。	输入
milli_sec	超时参数 milli_sec 设为-1 时，为阻塞接口；0 时为非阻塞接口；大于 0 时为超时等待时间，超时时间的单位为毫秒（ms）。	输入
src_frame_info	匹配原始图像帧信息。不能为空。	输出
dst_frame	匹配后图像。不能为空。详情请见《MPP 媒体处理软件 V5.0 开发参考》“系统控制”章节。	输出

参数名称

支持类型

地址对齐

分辨率

src_frame_info

原始图像支持：

OT_PIXEL_FORMAT_YVU_SEMIPLANAR_420/OT_PIXEL_FORMAT_YVU_SEMIPLANAR_422/OT_PIXEL_FORMAT_YUV_400

16 byte

128x64～2048x2048

校正图像支持：OT_PIXEL_FORMAT_YVU_SEMIPLANAR_420/OT_PIXEL_FORMAT_YVU_SEMIPLANAR_422/OT_PIXEL_FORMAT_YUV_400

16 byte

128x64～1920x1080

dst_frame

OT_PIXEL_FORMAT_S16

16 byte

128x64～1920x1080

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_dpu_match.h、ss_mpi_dpu_match.h
库文件：libss_dpu_match.a

【注意】

组必须已创建。
当组属性的队列深度不为0时，才能获取到图像。
当组属性的is_need_src_frame为TD_TRUE时，src_frame_info的src_frame才能获取到。
输出视差图以右图为基准图像。
输出结果数据元素格式为S10Q6(1bit符号位+9bit整数部分+6bit小数部分)。
输出图像分辨率与输入右图相同。

【举例】

无。

【相关主题】

ss_mpi_dpu_match_send_frame
ss_mpi_dpu_match_release_frame

ss_mpi_dpu_match_release_frame¶

【描述】

用户释放通道图像。

【语法】

td_s32 ss_mpi_dpu_match_release_frame(ot_dpu_match_grp match_grp, const ot_dpu_match_frame_info *src_frame_info, const ot_video_frame_info *dst_frame);

【参数】

参数名称

描述

输入/输出

match_grp

组号。

取值范围：[0, OT_DPU_MATCH_MAX_GRP_NUM)。

输入

src_frame_info

匹配原始图像帧信息。

不能为空。

输入

dst_frame

匹配后图像。

不能为空。

详情请见《MPP 媒体处理软件 V5.0 开发参考》“系统控制”章节。

输入

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_dpu_match.h、ss_mpi_dpu_match.h
库文件：libss_dpu_match.a

【注意】

组必须已创建。
src_frame_info/ dst_frame由ss_mpi_dpu_match_get_frame获取，与其配对使用。

【举例】

无。

【相关主题】

ss_mpi_dpu_match_send_frame
ss_mpi_dpu_match_get_frame

ss_mpi_dpu_match_set_grp_cost_param¶

【描述】

设置组的代价参数。

【语法】

td_s32 ss_mpi_dpu_match_set_grp_cost_param(ot_dpu_match_grp match_grp, const ot_dpu_match_cost_param *cost_param);

【参数】

参数名称

描述

输入/输出

match_grp

组号。

取值范围：[0, OT_DPU_MATCH_MAX_GRP_NUM)。

输入

cost_param

代价参数。

不能为空。

输入

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_dpu_match.h、ss_mpi_dpu_match.h
库文件：libss_dpu_match.a

【注意】

组必须已创建。

【举例】

无。

【相关主题】

ss_mpi_dpu_match_get_grp_cost_param

ss_mpi_dpu_match_get_grp_cost_param¶

【描述】

获取组的代价参数。

【语法】

td_s32 ss_mpi_dpu_match_get_grp_cost_param(ot_dpu_match_grp match_grp, ot_dpu_match_cost_param *cost_param);

【参数】

参数名称

描述

输入/输出

match_grp

组号。

取值范围：[0, OT_DPU_MATCH_MAX_GRP_NUM)。

输入

cost_param

代价参数。

不能为空。

输入

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_dpu_match.h、ss_mpi_dpu_match.h
库文件：libss_dpu_match.a

【注意】

组必须已创建。

【举例】

无。

【相关主题】

ss_mpi_dpu_match_set_grp_cost_param

ss_mpi_dpu_match_set_grp_param¶

【描述】

设置组参数。

【语法】

td_s32 ss_mpi_dpu_match_set_grp_param(ot_dpu_match_grp match_grp, const ot_dpu_match_param *param);

【参数】

参数名称

描述

输入/输出

match_grp

组号。

取值范围：[0, OT_DPU_MATCH_MAX_GRP_NUM)。

输入

param

匹配参数。

不能为空。

输入

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_dpu_match.h、ss_mpi_dpu_match.h
库文件：libss_dpu_match.a

【注意】

组必须已创建。
此接口兼容ss_mpi_dpu_match_set_grp_cost_param。

【举例】

无。

【相关主题】

ss_mpi_dpu_match_set_grp_cost_param
ss_mpi_dpu_match_get_grp_cost_param
ss_mpi_dpu_match_get_grp_param

ss_mpi_dpu_match_get_grp_param¶

【描述】

获取组参数。

【语法】

td_s32 ss_mpi_dpu_match_get_grp_param(ot_dpu_match_grp match_grp, ot_dpu_match_param *param);

【参数】

参数名称

描述

输入/输出

match_grp

组号。

取值范围：[0, OT_DPU_MATCH_MAX_GRP_NUM)。

输入

param

组参数。

不能为空。

输入

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_dpu_match.h、ss_mpi_dpu_match.h
库文件：libss_dpu_match.a

【注意】

组必须已创建。
此接口兼容ss_mpi_dpu_match_get_grp_cost_param。
必须设置param->version才能获取对应版本的参数，否则获取失败。

【举例】

无。

【相关主题】

ss_mpi_dpu_match_set_grp_cost_param
ss_mpi_dpu_match_get_grp_cost_param
ss_mpi_dpu_match_set_grp_param

数据类型和数据结构¶

DPU_MATCH相关数据类型、数据结构定义如下：

ot_dpu_match_grp：定义组号。
ot_dpu_match_pipe：定义管道号。
ot_dpu_match_chn：定义通道号。
ot_dpu_match_mask_mode：定义聚合模板模式。
ot_dpu_match_density_accuracy_mode：定义稠密精度模式。
ot_dpu_match_speed_accuracy_mode：定义速度精度模式。
ot_dpu_match_disparity_subpixel：定义是否计算亚像素枚举值。
ot_dpu_match_grp_attr：定义组属性。
ot_dpu_match_chn_attr：定义通道属性。
ot_dpu_match_frame_info：定义匹配图像帧信息。
ot_dpu_match_mem_info：定义一维内存信息。
ot_dpu_match_cost_param：定义代价参数。
ot_dpu_match_version：定义参数版本。
ot_dpu_match_param_v1：定义版本1参数。
ot_dpu_match_param_v2：定义版本2参数。
ot_dpu_match_param：定义匹配参数。
OT_DPU_MATCH_MAX_GRP_NUM：定义最大组数。
OT_DPU_MATCH_MAX_PIPE_NUM：定义最大管道数。
OT_DPU_MATCH_MAX_CHN_NUM：定义最大通道数。
OT_DPU_MATCH_IN_IMAGE_MAX_WIDTH：定义最大输入图像的宽度。
OT_DPU_MATCH_IN_IMAGE_MAX_HEIGHT：定义最大输入图像的高度。
OT_DPU_MATCH_IN_IMAGE_MIN_WIDTH：定义最小输入图像的宽度。
OT_DPU_MATCH_IN_IMAGE_MIN_HEIGHT：定义最小输入图像的高度。
OT_DPU_MATCH_OUT_IMAGE_MAX_WIDTH：定义最大输出图像的宽度。
OT_DPU_MATCH_OUT_IMAGE_MAX_HEIGHT：定义最大输出图像的高度。
OT_DPU_MATCH_OUT_IMAGE_MIN_WIDTH：定义最小输出图像的宽度。
OT_DPU_MATCH_OUT_IMAGE_MIN_HEIGHT：定义最小输出图像的高度。

ot_dpu_match_grp¶

【说明】

定义组号。

【定义】

typedef td_s32 ot_dpu_match_grp;

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

无。

ot_dpu_match_pipe¶

【说明】

定义管道号。

【定义】

typedef td_s32 ot_dpu_match_pipe;

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

无。

ot_dpu_match_chn¶

【说明】

定义通道号。

【定义】

typedef td_s32 ot_dpu_match_chn;

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

无。

ot_dpu_match_mask_mode¶

【说明】

定义聚合模板模式。

【定义】

typedef enum {
    OT_DPU_MATCH_MASK_DEFAULT_MODE = 0x0,
    OT_DPU_MATCH_MASK_1X1_MODE = 0x1,
    OT_DPU_MATCH_MASK_3X3_MODE = 0x2,
    OT_DPU_MATCH_MASK_5X5_MODE = 0x3,
    OT_DPU_MATCH_MASK_7X7_MODE = 0x4,
    OT_DPU_MATCH_MASK_9X9_MODE = 0x5,
    OT_DPU_MATCH_MASK_MODE_BUTT
} ot_dpu_match_mask_mode;

【成员】

成员名称	描述
OT_DPU_MATCH_MASK_DEFAULT_MODE	默认模板。
OT_DPU_MATCH_MASK_1X1_MODE	1x1模板。
OT_DPU_MATCH_MASK_3X3_MODE	3x3模板。
OT_DPU_MATCH_MASK_5X5_MODE	5x5模板。
OT_DPU_MATCH_MASK_7X7_MODE	7x7模板。
OT_DPU_MATCH_MASK_9X9_MODE	9x9模板。

【注意事项】

模板大小影响每一像素匹配时的关联区域大小,建议优先选择默认模板或9x9模板。

【相关数据类型及接口】

无。

ot_dpu_match_density_accuracy_mode¶

【说明】

定义稠密精度模式。

【定义】

typedef enum {
    OT_DPU_MATCH_DENSITY_ACCURACY_MODE_D0_A9 = 0x0,
    OT_DPU_MATCH_DENSITY_ACCURACY_MODE_D1_A8 = 0x1,
    OT_DPU_MATCH_DENSITY_ACCURACY_MODE_D2_A7 = 0x2,
    OT_DPU_MATCH_DENSITY_ACCURACY_MODE_D3_A6 = 0x3,
    OT_DPU_MATCH_DENSITY_ACCURACY_MODE_D4_A5 = 0x4,
    OT_DPU_MATCH_DENSITY_ACCURACY_MODE_D5_A4 = 0x5,
    OT_DPU_MATCH_DENSITY_ACCURACY_MODE_D6_A3 = 0x6,
    OT_DPU_MATCH_DENSITY_ACCURACY_MODE_D7_A2 = 0x7,
    OT_DPU_MATCH_DENSITY_ACCURACY_MODE_D8_A1 = 0x8,
    OT_DPU_MATCH_DENSITY_ACCURACY_MODE_D9_A0 = 0x9,
    OT_DPU_MATCH_DENSITY_ACCURACY_MODE_BUTT
} ot_dpu_match_density_accuracy_mode;

【成员】

成员名称	描述
OT_DPU_MATCH_DENSITY_ACCURACY_MODE_D0_A9	稠密度为0，精度为9。
OT_DPU_MATCH_DENSITY_ACCURACY_MODE_D1_A8	稠密度为1，精度为8。
OT_DPU_MATCH_DENSITY_ACCURACY_MODE_D2_A7	稠密度为2，精度为7。
OT_DPU_MATCH_DENSITY_ACCURACY_MODE_D3_A6	稠密度为3，精度为6。
OT_DPU_MATCH_DENSITY_ACCURACY_MODE_D4_A5	稠密度为4，精度为5。
OT_DPU_MATCH_DENSITY_ACCURACY_MODE_D5_A4	稠密度为5，精度为4。
OT_DPU_MATCH_DENSITY_ACCURACY_MODE_D6_A3	稠密度为6，精度为3。
OT_DPU_MATCH_DENSITY_ACCURACY_MODE_D7_A2	稠密度为7，精度为2。
OT_DPU_MATCH_DENSITY_ACCURACY_MODE_D8_A1	稠密度为8，精度为1。
OT_DPU_MATCH_DENSITY_ACCURACY_MODE_D9_A0	稠密度为9，精度为0。

【注意事项】

稠密度：DPU输出包含无效点的稀疏视差图，无效点越多稠密度越低。

例：OT_DPU_MATCH_DENSITY_ACCURACY_MODE_D0_A9表示稠密度最低，精度最高。建议采用OT_DPU_MATCH_DENSITY_ACCURACY_MODE_D9_A0。
不同场景下各模式表现会有所不同，可能出现相邻模式效果相似或颠倒的情况。

【相关数据类型及接口】

无。

ot_dpu_match_speed_accuracy_mode¶

【说明】

定义速度精度模式。

【定义】

typedef enum {
    OT_DPU_MATCH_SPEED_ACCURACY_MODE_SPEED = 0x0,
    OT_DPU_MATCH_SPEED_ACCURACY_MODE_ACCURACY = 0x1,
    OT_DPU_MATCH_SPEED_ACCURACY_MODE_BUTT
} ot_dpu_match_speed_accuracy_mode;

【成员】

成员名称	描述
OT_DPU_MATCH_SPEED_ACCURACY_MODE_SPEED	速度模式。
OT_DPU_MATCH_SPEED_ACCURACY_MODE_ACCURACY	精度模式。

【注意事项】

速度模式下，DPU处理速度提升约一倍，精度有所下降。

【相关数据类型及接口】

无。

ot_dpu_match_disparity_subpixel¶

【说明】

定义是否计算亚像素枚举值。

【定义】

typedef enum {
    OT_DPU_MATCH_DISPARITY_SUBPIXEL_DISABLE = 0x0,
    OT_DPU_MATCH_DISPARITY_SUBPIXEL_ENABLE = 0x1,
    OT_DPU_MATCH_DISPARITY_SUBPIXEL_BUTT
} ot_dpu_match_disparity_subpixel;

【成员】

成员名称	描述
OT_DPU_MATCH_DISPARITY_SUBPIXEL_DISABLE	不计算亚像素。
OT_DPU_MATCH_DISPARITY_SUBPIXEL_ENABLE	计算亚像素。

【注意事项】

计算亚像素时，输出视差包含6bit小数位，不计算时，输出视差仅包含整数位。

【相关数据类型及接口】

无。

ot_dpu_match_grp_attr¶

【说明】

定义组属性。

【定义】

typedef struct {
    ot_size left_image_size; /* left image size. */
    ot_size right_image_size; /* right image size. */
    ot_dpu_match_mask_mode match_mask_mode; /* aggregation mask mode. */
    ot_dpu_match_density_accuracy_mode density_accuracy_mode; /* adjust density-accuracy trade-off. */
    ot_dpu_match_speed_accuracy_mode speed_accuracy_mode; /* adjust speed-accuracy trade-off. */
    ot_dpu_match_disparity_subpixel  disparity_subpixel_en; /* calculate subpixel disparity or not. */
    td_u16 disparity_num; /* the number of disparity, it must be the multiple of 16. range:[16,224] */
    td_u16 disparity_start_pos; /* minimum disparity, it must be the multiple of 2. range:[0,126] */
    td_u32 depth; /* the depth of user image queue for getting match output image,
                           it can not be changed dynamic. range:[0,8] */
    td_bool is_need_src_frame; /* the flag of getting source videoframe.it will effect when bind dpu rect. */
    ot_dpu_match_mem_info assist_buf; /* assistance buffer. */
    ot_frame_rate_ctrl frame_rate; /* grp frame rate contrl. */
} ot_dpu_match_grp_attr;

【成员】

成员名称	描述
left_image_size	左图分辨率。取值范围: 宽[128, 1920]; 高[64, 1080]。 ot_size请参见《MPP 媒体处理软件 V5.0 开发参考》“系统控制”章节。
right_image_size	右图分辨率。取值范围: 宽[128, 1920]; 高[64, 1080]。 ot_size请参见《MPP 媒体处理软件 V5.0 开发参考》“系统控制”章节。
match_mask_mode	聚合模式。
density_accuracy_mode	稠密精度模式。
speed_accuracy_mode	速度精度模式。
disparity_subpixel_en	是否计算亚像素。
disparity_num	视差值数目，取值范围：[16, 224]，必须为16的倍数。
disparity_start_pos	最小视差起始地址，取值范围: [0, 126]。
depth	通道图像的队列长度，静态属性，不可动态更改。取值范围: [0, 8]。
is_need_src_frame	是否需要获取原始图像帧标志。
assist_buf	辅助内存。
frame_rate	组帧率。源帧率(src_frame_rate) 取值范围：-1 或[1, 240]；目的帧率(dst_frame_rate) 取值范围：[1, src_frame_rate]或-1（仅在src_frame_rate为-1时，目的帧率才能取值为-1）。 ot_frame_rate_ctrl请参见《MPP 媒体处理软件 V5.0 开发参考》“系统控制”章节。

【注意事项】

右图宽度需大于等于视差起始位置+视差数组（即组属性disparity_start_pos 和disparity_num）。
左图宽度需大于等于右图宽度。
左图右图高度相等。
分辨率宽、高要求偶数对齐。
disparity_start_pos必须为偶数。

【相关数据类型及接口】

无。

ot_dpu_match_chn_attr¶

【说明】

定义通道属性。

【定义】

typedef struct {
    ot_size image_size; /* output image size. */
} ot_dpu_match_chn_attr;

【成员】

成员名称

描述

image_size

目标分辨率。取值范围: 宽[128, 1920]; 高[64, 1080]。

分辨率大小需与组属性中右图分辨率一致。

ot_size请参见《MPP 媒体处理软件 V5.0 开发参考》“系统控制”章节。

【注意事项】

分辨率宽、高要求偶数对齐。

【相关数据类型及接口】

无。

ot_dpu_match_frame_info¶

【说明】

定义匹配图像帧信息。

【定义】

typedef struct {
    ot_video_frame_info src_frame[OT_DPU_MATCH_MAX_PIPE_NUM]; /* src_frame[0]:left frame,src_frame[1]:right frame */
    ot_video_frame_info rect_frame[OT_DPU_MATCH_MAX_PIPE_NUM]; /* rect_frame[0]:left frame,rect_frame[1]:right frame */
} ot_dpu_match_frame_info;

【成员】

成员名称

描述

src_frame[OT_DPU_RECT_MAX_PIPE_NUM]

左右原始图像帧。

ot_video_frame_info请参见《MPP 媒体处理软件 V5.0 开发参考》“系统控制”章节

rect_frame[OT_DPU_RECT_MAX_CHN_NUM]

左右校正图像帧。

ot_video_frame_info请参见《MPP 媒体处理软件 V5.0 开发参考》“系统控制”章节

【注意事项】

无。

【相关数据类型及接口】

无。

ot_dpu_match_mem_info¶

【说明】

定义一维内存信息。

【定义】

typedef struct {
    td_u64 phys_addr;
    td_u64 virt_addr;
    td_u32 size;
} ot_dpu_match_mem_info;

【成员】

成员名称	描述
phys_addr	内存块物理地址。
virt_addr	内存块虚拟地址。
size	内存块字节数,见图1。

【注意事项】

无。

【相关数据类型及接口】

无。

ot_dpu_match_cost_param¶

【说明】

定义代价参数。

【定义】

typedef struct {
    td_u16 first_penalty_coef; /* First penalty coefficient. Range: [0, 138] */
    td_u16 second_penalty_coef; /* First penalty coefficient. Range: [0, 138]*/
} ot_dpu_match_cost_param;

【成员】

成员名称

描述

first_penalty_coef

视差变化量为1个像素的惩罚系数。

取值范围：[0, 138]

second_penalty_coef

视差变化量大于1个像素的惩罚系数。

取值范围：[0, 138]

【注意事项】

无。

【相关数据类型及接口】

无。

ot_dpu_match_version¶

【说明】

定义参数版本。

【定义】

typedef enum {
    OT_DPU_MATCH_VERSION_V1 = 0,
    OT_DPU_MATCH_VERSION_V2 = 1,
    OT_DPU_MATCH_VERSION_BUTT
} ot_dpu_match_version;

【成员】

成员名称	描述
OT_DPU_MATCH_VERSION_V1	参数版本1。
OT_DPU_MATCH_VERSION_V2	参数版本2。

【注意事项】

无。

【相关数据类型及接口】

无。

ot_dpu_match_param_v1¶

【说明】

定义版本1参数。

【定义】

typedef ot_dpu_match_cost_param ot_dpu_match_param_v1;

【成员】

无。

【注意事项】

版本1参数为代价参数，与ot_dpu_match_cost_param等同。

【相关数据类型及接口】

无。

ot_dpu_match_param_v2¶

【说明】

定义版本2参数。

【定义】

typedef struct {
    td_u16 first_penalty_coef; /* first penalty coefficient. Range: [0, 138] */
    td_u16 second_penalty_coef; /* second penalty coefficient. Range: [0, 138] */
    td_u8 aggregate_coef; /* aggregate coefficient. Range: [0, 8] */
    td_u8 unique_ratio; /* uniqueness ratio. Range: [0, 31] */
    td_u8 fg_init_cost_zero_thr; /* the foreground overexposure area filter threshold,[1, 16] */
    td_u8 rsv;
} ot_dpu_match_param_v2;

【成员】

成员名称	描述
first_penalty_coef	视差变化量为1个像素的惩罚系数。取值范围：[0, 138]
second_penalty_coef	视差变化量大于1个像素的惩罚系数。取值范围：[0, 138]
aggregate_coef	聚合参数，用来控制算法在BM和SGBM之间的切换，值越小越接近BM，越大越接近SGBM。取值范围：[0, 8]
unique_ratio	控制视差滤除程度参数，值越大视差图越稠密，但噪声可能更多，越大。取值范围：[0, 31]
fg_init_cost_zero_thr	前景过度曝光区域过滤阈值。取值范围：[1, 16]

【注意事项】

无。

【相关数据类型及接口】

无。

ot_dpu_match_param¶

【说明】

定义匹配参数。

【定义】

typedef struct {
    ot_dpu_match_version version;
    union {
        ot_dpu_match_param_v1 v1;
        ot_dpu_match_param_v2 v2;
    };
} ot_dpu_match_param;

【成员】

成员名称	描述
version	参数版本。
v1	版本1版本。
v2	版本2版本。

【注意事项】

version不同值取不同的联合体变量。如OT_DPU_MATCH_VERSION_V1时，v1有效。
高版本兼容低版本，如v2兼容v1版本。
如某些参数想使用默认参数，可以通过先调用 ss_mpi_dpu_match_get_grp_param获取到默认值，更改完参数，再调用ss_mpi_dpu_match_set_grp_param设置参数。

【相关数据类型及接口】

无。

OT_DPU_MATCH_MAX_GRP_NUM¶

【说明】

定义最大组数。

【定义】

#define OT_DPU_MATCH_MAX_GRP_NUM           16

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

无。

OT_DPU_MATCH_MAX_PIPE_NUM¶

【说明】

定义最大管道数。

【定义】

#define OT_DPU_MATCH_MAX_PIPE_NUM          2

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

无。

OT_DPU_MATCH_MAX_CHN_NUM¶

【说明】

定义最大管道数。

【定义】

#define OT_DPU_MATCH_MAX_CHN_NUM          1

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

无。

OT_DPU_MATCH_IN_IMAGE_MAX_WIDTH¶

【说明】

定义最大输入图像的宽度。

【定义】

#define OT_DPU_MATCH_IN_IMAGE_MAX_WIDTH    1920

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

无。

OT_DPU_MATCH_IN_IMAGE_MAX_HEIGHT¶

【说明】

定义最大输入图像的高度。

【定义】

#define OT_DPU_MATCH_IN_IMAGE_MAX_HEIGHT   1080

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

无。

OT_DPU_MATCH_IN_IMAGE_MIN_WIDTH¶

【说明】

定义最小输入图像的宽度。

【定义】

#define OT_DPU_MATCH_IN_IMAGE_MIN_WIDTH    128

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

无。

OT_DPU_MATCH_IN_IMAGE_MIN_HEIGHT¶

【说明】

定义最小输入图像的高度。

【定义】

#define OT_DPU_MATCH_IN_IMAGE_MIN_HEIGHT   64

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

无。

OT_DPU_MATCH_OUT_IMAGE_MAX_WIDTH¶

【说明】

定义最大输出图像的宽度。

【定义】

#define OT_DPU_MATCH_OUT_IMAGE_MAX_WIDTH   1920

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

无。

OT_DPU_MATCH_OUT_IMAGE_MAX_HEIGHT¶

【说明】

定义最大输出图像的高度。

【定义】

#define OT_DPU_MATCH_OUT_IMAGE_MAX_HEIGHT  1080

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

无。

OT_DPU_MATCH_OUT_IMAGE_MIN_WIDTH¶

【说明】

定义最小输出图像的宽度。

【定义】

#define OT_DPU_MATCH_OUT_IMAGE_MIN_WIDTH   128

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

无。

OT_DPU_MATCH_OUT_IMAGE_MIN_HEIGHT¶

【说明】

定义最小输出图像的高度。

【定义】

#define OT_DPU_MATCH_OUT_IMAGE_MIN_HEIGHT  64

【成员】

无。

【注意事项】

无。

【相关数据类型及接口】

无。

错误码¶

本模块API错误码如下所示。

表 1 DPU_MATCH模块API错误码

错误代码	宏定义	描述
0xa0368001	OT_ERR_DPU_MATCH_INVALID_DEV_ID	设备ID超出合法范围
0xa0368003	OT_ERR_DPU_MATCH_INVALID_CHN_ID	通道号错误或无效区域句柄
0xa0368005	OT_ERR_DPU_MATCH_INVALID_GRP_ID	组号错误或无效区域句柄
0xa0368007	OT_ERR_DPU_MATCH_ILLEGAL_PARAM	参数超出合法范围
0xa0368008	OT_ERR_DPU_MATCH_EXIST	重复创建已存在的设备、通道或资源
0xa0368009	OT_ERR_DPU_MATCH_UNEXIST	试图使用或者销毁不存在的设备、通道或者资源
0xa036800a	OT_ERR_DPU_MATCH_NULL_PTR	函数参数中有空指针
0xa036800c	OT_ERR_DPU_MATCH_NOT_SUPPORT	不支持的参数或者功能
0xa036800d	OT_ERR_DPU_MATCH_NOT_PERM	该操作不允许，如试图修改静态配置参数
0xa0368014	OT_ERR_DPU_MATCH_NO_MEM	分配内存失败，如系统内存不足
0xa0368015	OT_ERR_DPU_MATCH_NO_BUF	分配缓存失败，如申请的图像缓冲区太大
0xa0368016	OT_ERR_DPU_MATCH_BUF_EMPTY	缓冲区中无图像
0xa0368018	OT_ERR_DPU_MATCH_NOT_READY	系统没有初始化或没有加载相应模块
0xa0368022	OT_ERR_DPU_MATCH_BUSY	系统忙
0xa0368040	OT_ERR_DPU_MATCH_SYS_TIMEOUT	系统超时
0xa0368041	OT_ERR_DPU_MATCH_OPEN_FILE	打开文件失败
0xa0368042	OT_ERR_DPU_MATCH_READ_FILE	读文件失败
0xa0368043	OT_ERR_DPU_MATCH_WRITE_FILE	写文件失败

Proc调试信息¶

概述¶

调试信息采用了Linux下的proc文件系统，可实时反映当前系统的运行状态，所记录的信息可供问题定位及分析时使用。

【文件目录】

/proc/umap

【信息查看方法】

在控制台上可以使用cat命令查看信息，cat /proc/umap/match；也可以使用其他常用的文件操作命令，例如 cp /proc/umap/match ./，将文件拷贝到当前目录。
在应用程序中可以将上述文件当作普通只读文件进行读操作，例如fopen、fread等。

说明： 参数在描述时有以下两种情况需要注意：

取值为{0, 1}的参数，如未列出具体取值和含义的对应关系，则参数为1时表示肯定，为0时表示否定。

取值为{aaa, bbb, ccc}的参数，未列出具体取值和含义的对应关系，但可直接根据取值aaa、bbb或ccc判断参数含义。

Proc信息说明¶

【调试信息】

# cat /proc/umap/match
[DPU_MATCH] Version: [Vx.x.x.x B0xx Release], Build Time[mm  dd yyyy, hh:mm:ss]
----------------------------------------dpu match hardware status----------------------------------------
  is_busy      sys_timeout_cnt
    n                0
----------------------------------------dpu match grp attr1------------------------------------------------
  grp_id  is_start  grp_state  is_need_src_frame  depth  src_frame_rate  dst_frame_rate  left_width  left_height
       0         y     create                  y      1              -1              -1        1050          560
 
----------------------------------------dpu match grp attr2------------------------------------------------
  right_width  right_height  match_mask_mode  density_accuracy_mode  speed_accuracy_mode  disparity_subpixel_en
     1050           560              9X9                  d9_a0             accuracy                      1
 
----------------------------------------dpu match grp attr3------------------------------------------------  
disparity_num  disparity_start_pos  first_penalty_coef  second_penalty_coef  assist_buf_addr  assist_buf_size
        80                0                   8                  138         882a2000       372928
----------------------------------------dpu match chn attr-------------------------------------------------
  grp_id  chn_id  enable   width  height
     0       0       y    1280     720
----------------------------------------dpu match pipe queue----------------------------------------------
  grp_id  busy_num  free_num
       0         0         8
----------------------------------------dpu match out queue-----------------------------------------------
  grp_id  busy_num  free_num
       0         1         0
----------------------------------------dpu match work queue---------------------------------------------
  busy_num  free_num
         0       128
----------------------------------------dpu match grp status-----------------------------------------------
  grp_id  frame_rate       start_cnt  start_fail_cnt  out_frame_lost  in_frame_lost
       0           1               1               0               0              0
----------------------------------------dpu match run-time info1------------------------------------------
  irq_cnt_per_sec  max_irq_cnt_per_sec  irq_cnt_last_sec  irq_cnt_cur  cur_irq_cost_time  max_irq_cost_time
   0                   0                 0          694               35            35
 
----------------------------------------dpu match run-time info2------------------------------------------
  irq_cost_per_sec  max_irq_cost_per_sec  irq_time_total   proc_cost_per_frame  hw_proc_cost_per_frame     runtime
           0                     0           16340                 23137                   23108          24

【调试信息分析】

记录当前DPU_MATCH属性配置以及状态信息。

【参数说明】

参数		描述
dpu match hardware status DPU MATCH 硬件工作状态信息	is_busy	DPU MATCH 硬件是否忙。 y: 硬件忙; n: 硬件空闲。
dpu match hardware status DPU MATCH 硬件工作状态信息	sys_timeout_cnt	DPU MATCH 系统超时次数。
dpu match grp attr1 DPU MATCH 组属性信息。	grp_id	组ID号。有效范围：[0, 16)。
	is_start	组启动状态。 y: 启动； n: 未启动。
	grp_state	组工作状态。 create:创建; destroying:销毁。
	is_need_src_frame	是否需要获取原始图像标志。 y: 需要获取原始图像； n: 不需要获取原始图像。
	depth	输出队列深度。取值范围: [0, 8]。
	src_frame_rate	组源帧率。
	dst_frame_rate	组目标帧率。
	left_width	输入左图分辨率的宽。取值范围：[128, 1920]。
	left_height	输入左图分辨率的高。取值范围：[64, 1080]。
	right_width	输入右图分辨率的宽。取值范围：[128, 1920]。
	right_height	输入右图分辨率的高。取值范围：[64, 1080]。
dpu match grp attr2 DPU MATCH 组属性信息。	match_mask_mode	聚合模板模式。取值参考对应的枚举定义。
	density_accuracy_mode	稠密度精度模式。取值参考对应的枚举定义。
	speed_accuracy_mode	速度精度模式。取值参考对应的枚举定义。
	disparity_subpixel_en	亚像素使能。取值参考对应的枚举定义。
	disparity_num	视差数目。取值参考组属性结构体描述。
	disparity_start_pos	起始视差位置。取值参考组属性结构体描述。
	first_penalty_coef	视差变化量为1个像素的惩罚系数。取值范围：[0, 138]
	second_penalty_coef	视差变化量大于1个像素的惩罚系数。取值范围：[0, 138]
	assist_buf_addr	辅助内存地址。
	assist_buf_size	辅助内存大小。
dpu match chn attr DPU MATCH通道属性信息	grp_id	组ID号。有效范围：[0, 16)。
	chn_id	通道ID号。有效范围：[0, 1)。
	enable	通道使能标志。 y: 使能; n: 未使能。
	width	通道输出的目标图像分辨率的宽。取值范围: [128, 1920]。
	height	通道输出的目标图像分辨率的高。取值范围: [64, 1080]。
dpu match pipe queue DPU MATCH 输入管道队列信息	grp_id	组ID号。有效范围：[0, 16)。
	busy_num	已用节点数。
	free_num	可用节点数。
dpu match out queue DPU MATCH 输出通道队列信息	grp_id	组ID号。有效范围：[0, 16)。
	busy_num	已用节点数。
	free_num	可用节点数。
dpu match work queue DPU MATCH 工作队列信息	busy_num	已用节点数。
dpu match work queue DPU MATCH 工作队列信息	free_num	可用节点数。
dpu match grp status DPU MATCH组状态信息	grp_id	组ID号。有效范围：[0, 16)。
	frame_rate	输出帧率。
	start_cnt	任务启动次数。
	start_fail_cnt	任务启动失败次数。
	out_frame_lost	因队列满丢失的输出图像数
	in_frame_lost	因队列满丢失的输入图像数。
dpu match run-time info DPU MATCH运行时相关信息	irq_cnt_per_sec	最近一次的1秒内中断执行次数。
	max_irq_cnt_per_sec	历史上的1秒内最大的中断执行次数。
	irq_cnt_last_sec	上一秒上报中断总次数。
	irq_cnt_cur	DPU MATCH产生中断的总次数。
	cur_irq_cost_time	最近一次执行中断的执行耗时。单位：us
	max_irq_cost_time	执行一次中断的最大耗时。单位：us
	irq_cost_per_sec	最近一秒执行中断的执行耗时。单位：us
	max_irq_cost_per_sec	历史上一秒执行中断的最大执行耗时。单位：us
	irq_time_total	中断处理总时间。单位：us
	proc_cost_per_frame	单帧图像处理的总时间。单位：us
	hw_proc_cost_per_frame	单帧图像处理的硬件时间。单位：us
	runtime	DPU MATCH运行总时间。单位：s

DSP¶

概述¶

DSP（Digital Signal Process）是SVP 平台下的可编程硬件加速模块。用户基于DSP开发_识别_分析方案可以加速_识别_分析，降低CPU占用。

须知： 本章节对于生态开源版本SS928V100/SS927V100暂不支持。

功能描述¶

重要概念¶

句柄(handle)

用户在调用DSP处理任务时，系统会为每个任务分配一个handle，用于标识不同的任务。
查询(query)

用户根据系统返回的handle，调用ss_mpi_svp_dsp_query可以查询对应算子任务是否完成。

模块参数¶

dsp_max_node_num

DSP模块各个优先级队列节点最大数目。用户可以依据实际使用场景配置合理的最大节点数，以减少队列节点对系统内存的占用。取值范围：[20, 51]。默认值为30。

使用方法：

Linux系统通过加载xxxx_dsp.ko时设置dsp_max_node_num。
dsp_init_mode

DSP模块初始化模式。用户可以依据业务实际情况配置不同初始化模式，取值只有0或者1两个值，默认值为0。
- 初始化模式取值为0时，只要整个媒体系统退出都需要调用DSP相关的下电，关闭DSP接口才能退出系统，重新使用DSP时，需要按照正常流程上电，加载DSP镜像，使能DSP。
- 初始化模式取值为1时，整个媒体系统退出时，不需要执行DSP的关闭和下电接口，保持DSP镜像系统是运行状态。重新使用DSP时，不需要再次加载DSP镜像。
使用方法：

Linux系统通过加载xxxx_dsp.ko时设置dsp_init_mode。

API参考¶

DSP ARM端模块API接口操作。

提供以下API：

ss_mpi_svp_dsp_power_on：DSP上电。
ss_mpi_svp_dsp_power_off：DSP下电。
ss_mpi_svp_dsp_load_bin：加载DSP Bin。
ss_mpi_svp_dsp_enable_core：使能DSP核，使其工作。
ss_mpi_svp_dsp_disable_core：去使能DSP核，使其停止工作。
ss_mpi_svp_dsp_rpc：远程处理任务。
ss_mpi_svp_dsp_query：查询任务完成情况。

ss_mpi_svp_dsp_power_on¶

【描述】

DSP上电。

【语法】

td_s32 ss_mpi_svp_dsp_power_on(ot_svp_dsp_id dsp_id);

【参数】

参数名称	描述	输入/输出
dsp_id	DSP ID号。	输入

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_svp.h、ot_common_dsp.h、ss_mpi_dsp.h
库文件：libss_dsp.a

【注意】

在加载DSP镜像前，必须先调用ss_mpi_svp_dsp_power_on接口使DSP上电，否则加载镜像时会挂死。

【举例】

无。

【相关主题】

无。

ss_mpi_svp_dsp_power_off¶

【描述】

DSP下电。

【语法】

td_s32 ss_mpi_svp_dsp_power_off(ot_svp_dsp_id dsp_id);

【参数】

参数名称	描述	输入/输出
dsp_id	DSP ID号。	输入

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_svp.h、ot_common_dsp.h、ss_mpi_dsp.h
库文件：libss_dsp.a

【注意】

无。

【举例】

无。

【相关主题】

无。

ss_mpi_svp_dsp_load_bin¶

【描述】

加载DSP 镜像二进制文件。

【语法】

td_s32 ss_mpi_svp_dsp_load_bin(const td_char *bin_file_name, ot_svp_dsp_mem_type mem_type);

【参数】

参数名称

描述

输入/输出

bin_file_name

Bin 文件名。

不能为空。

输入

mem_type

DSP 内存类型。

输入

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_svp.h、ot_common_dsp.h、ss_mpi_dsp.h
库文件：libss_dsp.a

【注意】

用户要保证加载文件的完整性，否则可能出现DSP启动失败、系统挂死等问题。

【举例】

无。

【相关主题】

无。

ss_mpi_svp_dsp_enable_core¶

【描述】

使能DSP核，使其工作。

【语法】

td_s32 ss_mpi_svp_dsp_enable_core(ot_svp_dsp_id dsp_id);

【参数】

参数名称	描述	输入/输出
dsp_id	DSP ID号。	输入

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_svp.h、ot_common_dsp.h、ss_mpi_dsp.h
库文件：libss_dsp.a

【注意】

无。

【举例】

无。

【相关主题】

无。

ss_mpi_svp_dsp_disable_core¶

【描述】

去使能DSP核，使其停止工作。

【语法】

td_s32 ss_mpi_svp_dsp_disable_core(ot_svp_dsp_id dsp_id);

【参数】

参数名称	描述	输入/输出
dsp_id	DSP ID号。	输入

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_svp.h、ot_common_dsp.h、ss_mpi_dsp.h
库文件：libss_dsp.a

【注意】

无。

【举例】

无。

【相关主题】

无。

ss_mpi_svp_dsp_rpc¶

【描述】

远程处理任务。

【语法】

td_s32 ss_mpi_svp_dsp_rpc(ot_svp_dsp_handle *handle, const ot_svp_dsp_msg *msg, ot_svp_dsp_id dsp_id, ot_svp_dsp_pri pri);

【参数】

参数名称	描述	输入/输出
handle	handle指针。不能为空。	输出
msg	处理消息体。不能为空。	输入
dsp_id	DSP Id号。	输入
pri	任务优先级。	输入

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_svp.h、ot_common_dsp.h、ss_mpi_dsp.h
库文件：libss_dsp.a

【注意】

无。

【举例】

无。

【相关主题】

无。

ss_mpi_svp_dsp_query¶

【描述】

查询任务完成情况。

【语法】

td_s32 ss_mpi_svp_dsp_query(ot_svp_dsp_id dsp_id, ot_svp_dsp_handle handle, td_bool *is_finish, td_bool is_block);

【参数】

参数名称	描述	输入/输出
dsp_id	DSP Id号。	输入
handle	任务的handle。	输入
is_finish	任务完成状态指针。不能为空。	输出
is_block	是否阻塞查询标志。	输入

【返回值】

返回值	描述
0	成功。
非0	失败，参见错误码。

【需求】

头文件：ot_common_svp.h、ot_common_dsp.h、ss_mpi_dsp.h
库文件：libss_dsp.a

【注意】

无。

【举例】

无。

【相关主题】

无。

数据类型和数据结构¶

DSP相关数据类型、数据结构定义如下：

ot_svp_dsp_handle：定义DSP句柄。
ot_svp_dsp_id：定义DSP ID。
ot_svp_dsp_pri：定义优先级。
ot_svp_dsp_mem_type：定义内存类型。
ot_svp_dsp_cmd：定义命令。
ot_svp_dsp_msg：定义消息格式。

ot_svp_dsp_handle¶

【说明】

定义DSP 句柄。

【定义】

typedef td_s32 ot_svp_dsp_handle;

【成员】

成员名称	描述
ot_svp_dsp_handle	DSP 句柄。

【注意事项】

无。

【相关数据类型及接口】

无。

ot_svp_dsp_id¶

【说明】

定义DSP ID。

【定义】

typedef enum {
    OT_SVP_DSP_ID_0 = 0x0,
    OT_SVP_DSP_ID_1 = 0x1,
    OT_SVP_DSP_ID_BUTT
} ot_svp_dsp_id;

【成员】

成员名称	描述
OT_SVP_DSP_ID_0	DSP ID 0。
OT_SVP_DSP_ID_1	DSP ID 1。

【注意事项】

无。

【相关数据类型及接口】

无。

ot_svp_dsp_pri¶

【说明】

定义优先级。

【定义】

typedef enum {
    OT_SVP_DSP_PRI_0 = 0x0,
    OT_SVP_DSP_PRI_1 = 0x1,
    OT_SVP_DSP_PRI_2 = 0x2,
    OT_SVP_DSP_PRI_BUTT
} ot_svp_dsp_pri;

【成员】

成员名称	描述
OT_SVP_DSP_PRI_0	优先级0 最高。
OT_SVP_DSP_PRI_1	优先级1。
OT_SVP_DSP_PRI_2	优先级2。

【注意事项】

无。

【相关数据类型及接口】

无。

ot_svp_dsp_mem_type¶

【说明】

定义内存类型。

【定义】

typedef enum {
    OT_SVP_DSP_MEM_TYPE_SYS_DDR_DSP_0 = 0x0,
    OT_SVP_DSP_MEM_TYPE_IRAM_DSP_0 = 0x1,
    OT_SVP_DSP_MEM_TYPE_DRAM_0_DSP_0 = 0x2,
    OT_SVP_DSP_MEM_TYPE_DRAM_1_DSP_0 = 0x3,
 
    OT_SVP_DSP_MEM_TYPE_SYS_DDR_DSP_1 = 0x4,
    OT_SVP_DSP_MEM_TYPE_IRAM_DSP_1 = 0x5,
    OT_SVP_DSP_MEM_TYPE_DRAM_0_DSP_1 = 0x6,
    OT_SVP_DSP_MEM_TYPE_DRAM_1_DSP_1 = 0x7,
 
    OT_SVP_DSP_MEM_TYPE_BUTT
} ot_svp_dsp_mem_type;

【成员】

成员名称	描述
OT_SVP_DSP_MEM_TYPE_SYS_DDR_DSP_0	DSP0使用的系统DDR内存地址空间。
OT_SVP_DSP_MEM_TYPE_IRAM_DSP_0	DSP0内部IRAM地址空间。
OT_SVP_DSP_MEM_TYPE_DRAM_0_DSP_0	DSP0内部DRAM0地址空间。
OT_SVP_DSP_MEM_TYPE_DRAM_1_DSP_0	DSP0内部DRAM1地址空间。
OT_SVP_DSP_MEM_TYPE_SYS_DDR_DSP_1	DSP1使用的系统DDR内存地址空间。
OT_SVP_DSP_MEM_TYPE_IRAM_DSP_1	DSP1内部IRAM地址空间。
OT_SVP_DSP_MEM_TYPE_DRAM_0_DSP_1	DSP1内部DRAM0地址空间。
OT_SVP_DSP_MEM_TYPE_DRAM_1_DSP_1	DSP1内部DRAM1地址空间。

【注意事项】

无。

【相关数据类型及接口】

无。

ot_svp_dsp_cmd¶

【说明】

定义命令。

【定义】

typedef enum {
    OT_SVP_DSP_CMD_INIT = 0x0,
    OT_SVP_DSP_CMD_EXIT = 0x1,
    OT_SVP_DSP_CMD_DILATE_3X3 = 0x2,
    OT_SVP_DSP_CMD_ERODE_3X3 = 0x3,
    OT_SVP_DSP_CMD_BUTT
} ot_svp_dsp_cmd;

【成员】

成员名称	描述
OT_SVP_DSP_CMD_INIT	初始化，系统命令，用户无需关心。
OT_SVP_DSP_CMD_EXIT	去初始化，系统命令，用户无需关心。
OT_SVP_DSP_CMD_DILATE_3X3	Dilate 3x3命令。
OT_SVP_DSP_CMD_ERODE_3X3	Erode 3x3命令。

【注意事项】

用户增加的命令必须OT_SVP_DSP_CMD_BUTT + 1以后，不能与已有重合。

【相关数据类型及接口】

无。

ot_svp_dsp_msg¶

【说明】

定义消息格式。

【定义】

typedef struct {
    td_u32 cmd;     /* CMD ID, user-defined SVP_DSP_CMD_BUTT + */
    td_u32 msg_id;   /* Message ID */
    td_u64 body;    /* Message body */
    td_u32 body_len; /* Length of pBody */
} ot_svp_dsp_msg;

【成员】

成员名称	描述
cmd	消息命令。
msg_id	消息ID。
body	消息体。
body_len	消息体大小。

【注意事项】

无。

【相关数据类型及接口】

无。

错误码¶

DSP模块API错误码如下所示。

表 1 DSP模块API错误码

错误代码	宏定义	描述
0xa0348001	OT_ERR_SVP_DSP_INVALID_DEV_ID	设备ID超出合法范围
0xa0348003	OT_ERR_SVP_DSP_INVALID_CHN_ID	通道组号错误或无效区域句柄
0xa0348007	OT_ERR_SVP_DSP_ILLEGAL_PARAM	参数超出合法范围
0xa0348008	OT_ERR_SVP_DSP_EXIST	重复创建已存在的设备、通道或资源
0xa0348009	OT_ERR_SVP_DSP_UNEXIST	试图使用或者销毁不存在的设备、通道或者资源
0xa034800a	OT_ERR_SVP_DSP_NULL_PTR	函数参数中有空指针
0xa034800b	OT_ERR_SVP_DSP_NOT_CONFIG	模块没有配置
0xa034800c	OT_ERR_SVP_DSP_NOT_SUPPORT	不支持的参数或者功能
0xa034800d	OT_ERR_SVP_DSP_NOT_PERM	该操作不允许，如试图修改静态配置参数
0xa0348014	OT_ERR_SVP_DSP_NO_MEM	分配内存失败，如系统内存不足
0xa0348015	OT_ERR_SVP_DSP_NO_BUF	分配缓存失败，如申请的图像缓冲区太大
0xa0348016	OT_ERR_SVP_DSP_BUF_EMPTY	缓冲区中无图像
0xa0348017	OT_ERR_SVP_DSP_BUF_FULL	缓冲区中图像满
0xa0348018	OT_ERR_SVP_DSP_NOT_READY	系统没有初始化或没有加载相应模块
0xa0348021	OT_ERR_SVP_DSP_BAD_ADDR	地址非法
0xa0348022	OT_ERR_SVP_DSP_BUSY	系统忙
0xa0348040	OT_ERR_SVP_DSP_SYS_TIMEOUT	系统超时
0xa0348041	OT_ERR_SVP_DSP_QUERY_TIMEOUT	Query查询超时
0xa0348042	OT_ERR_SVP_DSP_OPEN_FILE	打开文件失败
0xa0348043	OT_ERR_SVP_DSP_READ_FILE	读文件失败

Proc调试信息¶

概述¶

调试信息采用了Linux下的proc文件系统，可实时反映当前系统的运行状态，所记录的信息可供问题定位及分析时使用。

【文件目录】

/proc/umap

【信息查看方法】

在控制台上可以使用cat命令查看信息，cat /proc/umap/dsp；也可以使用其他常用的文件操作命令，例如 cp /proc/umap/dsp ./，将文件拷贝到当前目录。
在应用程序中可以将上述文件当作普通只读文件进行读操作，例如fopen、fread等。

说明： 参数在描述时有以下2种情况需要注意：

取值为{0, 1}的参数，如未列出具体取值和含义的对应关系，则参数为1时表示肯定，为0时表示否定。

取值为{aaa, bbb, ccc}的参数，未列出具体取值和含义的对应关系，但可直接根据取值aaa、bbb或ccc判断参数含义

Proc信息说明¶

【调试信息】

~ # cat /proc/umap/dsp 
 
[DSP] Version: [Vx.x.x.x B0xx Release], Build Time[mm  dd yyyy, hh:mm:ss]
 
 ----------------------------------------module param-------------------------------------------------------------------
    max_node_num   dsp_init_mode
              30               0
 
----------------------------------------dsp config attr-----------------------------------------------------------------
   core_id        sram_addr
         0        40210000
         1        42000000
 
----------------------------------------dsp core status-----------------------------------------------------------------
   core_id    enable
         0       yes
         1        no
 
----------------------------------------dsp pri status------------------------------------------------------------------
   core_id    pri    create
         0    0       yes
         0    1        no
         0    2        no
         1    0        no
         1    1        no
         1    2        no
 
----------------------------------------dsp task info-------------------------------------------------------------------
   core_id  pri       hnd  task_fsh  hnd_wrap  free_num  work_num
         0    0       298       298         0        30         0
         0    1         0         0         0        30         0
         0    2         0         0         0        30         0
         1    0         0         0         0        30         0
         1    1         0         0         0        30         0
         1    2         0         0         0        30         0
 
----------------------------------------dsp runtime info----------------------------------------------------------------
core_id   pri cnt_per_sec  max_cnt_per_sec    total_int_cnt_last_sec     total_int_cnt   qt_cnt   cost_tm  m_cost_tm  cost_tm_per_sec  m_cost_tm_per_sec  total_int_cost_tm
         0    0         31               32                     281            298        0         5          7              159                166               1554
         0    1          0                0                       0              0        0         0          0                0                  0                  0
         0    2          0                0                       0              0        0         0          0                0                  0                  0
         1    0          0                0                       0              0        0         0          0                0                  0                  0
         1    1          0                0                       0              0        0         0          0                0                  0                  0
         1    2          0                0                       0              0        0         0          0                0                  0                  0
 
    run_tm
        35
        35
        35
        35
        35
        35
 
----------------------------------------dsp invoke info-----------------------------------------------------------------
   core_id         pri       rpc
         0         0       298
         0         1         0
         0         2         0
         1         0         0
         1         1         0
         1         2         0

【调试信息分析】

记录当前DSP工作状态资源信息，主要包括DSP 队列状态信息，任务状态信息，运行时状态信息和调用信息。

【参数说明】

参数		描述
module param 模块参数	max_node_num	最大节点数，也即可保存处理结果最大数量。
module param 模块参数	dsp_init_mode	初始化模式，只有0或者1。
dsp config attr 配置属性	core_id	DSP 核ID。
dsp config attr 配置属性	sram_addr	镜像在DDR的首地址。
dsp core status核状态	core_id	DSP 核ID。
dsp core status核状态	enable	便能状态：yes为使能，no为非使能。
dsp pri status优先级通道状态	core_id	DSP 核ID。
	pri	任务优先级。
	create	创建状态：yes为创建，no为没有创建。
dsp task info任务信息	core_id	DSP 核ID。
	pri	任务优先级。
	hnd	当前可分配的任务handle号。
	task_fsh	当前已完成任务handle号。
	hnd_wrap	用户handle号分配发生回写的次数。
	free_num	空闲节点数。
	work_num	已使用任务数。
dsp runtime info运行时相关信息	core_id	DSP核ID。
	pri	任务优先级。
	cnt_per_sec	最近一次的1秒内中断执行次数。
	max_cnt_per_sec	历史上的1秒内最大的中断执行次数。
	total_int_cnt_last_sec	上一秒上报中断总次数。
	total_int_cnt	DSP产生中断的总次数。
	qt_cnt	DSP查询超时中断次数。
	cost_tm	最近一次执行中断的执行耗时。单位：us
	m_cost_tm	执行一次中断的最大耗时。单位：us
	cost_tm_per_sec	最近一秒执行中断的执行耗时。单位：us
	m_cost_tm_per_sec	历史上一秒执行中断的最大执行耗时。单位：us
	total_int_cost_tm	中断处理总时间。单位：us
	run_tm	DSP运行总时间。单位：s
dsp invoke info调用信息	core_id	DSP核ID。
	pri	任务优先级。
	rpc	RPC调用次数。

【注意】

无