TORQ C API 参考
概述
TORQ C API 是 UCA Runtime(运行时库)的 C 语言接口。通过使用 TORQ C API,开发者可以利用 NPU 的计算能力完成高效的 TORQ 模型推理。本文对 TORQ C API 的各个函数、数据结构以及返回值定义进行说明。
支持硬件平台
TORQ C API 适用如下硬件平台。
| 支持硬件平台 |
|---|
| A200 |
| A210 |
TORQ 编译说明
开发者编译应用时要包含接口函数所在的头文件,并且根据使用的硬件平台和系统类型,链接相应 UCA 运行时库。以下对 TORQ C API 头文件和运行时库文件进行说明。
TORQ C API 头文件
torq_api.h 中定义了部署 TORQ 模型的基础接口和数据结构。
Linux 平台 TORQ 运行时库
对于 A200/A210 系列硬件平台, UCA 运行时库文件libtorqrt.so,路径为 <sdk_path>/uca/runtime,其中 <sdk_path> 是 NPU 软件开发包的路径。
TORQ C API 说明
各个硬件平台的 C API 支持情况
TORQ C API 的接口以及接口参数对不同芯片平台的支持情况可能存在差异。各个硬件平台的 TORQ C API 接口支持情况如下表所示。
| 序号 | TORQ C API | A200 | A210 |
|---|---|---|---|
| 1 | torq_init | √ | √ |
| 2 | torq_destroy | √ | √ |
| 3 | torq_query | √ | √ |
| 4 | torq_inputs_set | √ | √ |
| 5 | torq_run | √ | √ |
| 6 | torq_outputs_get | √ | √ |
| 7 | torq_outputs_release | √ | √ |
| 8 | torq_create_mem_from_phys | √ | √ |
| 9 | torq_create_mem_from_fd | √ | √ |
| 10 | torq_create_mem | √ | √ |
| 11 | torq_destroy_mem | √ | √ |
| 12 | torq_set_io_mem | √ | √ |
| 13 | torq_set_input_shapes | √ | √ |
TORQ C API 接口调用流程
关于 TORQ C API 接口调用流程,请见 TORQ SDK 介绍。
基础数据结构定义
torq_sdk_version
描述
TORQ SDK 的版本信息。
成员
| 成员变量 | 数据类型 | 含义 |
|---|---|---|
| api_version | char[] | SDK 的版本信息。 |
| drv_version | char[] | SDK 所基于的驱动版本信息。 |
torq_input_output_num
描述
输入/输出 tensor 个数。
成员
| 成员变量 | 数据类型 | 含义 |
|---|---|---|
| n_input | uint32_t | 输入 tensor 个数。 |
| n_output | uint32_t | 输出 tensor 个数。 |
torq_input_range
描述
表示一个输入的支持形状列表信息。
成员
| 成员变量 | 数据类型 | 含义 |
|---|---|---|
| index | uint32_t | 表示该形状对应输入的索引位置。 |
| shape_number | uint32_t | 表示 TORQ 模型支持的输入形状个数。 |
| fmt | torq_tensor_format | 表示形状对应的数据布局格式。 |
| name | char[] | 表示输入的名称。 |
| dyn_range | uint32_t[][] | 表示输入形状列表,它是包含多个形状数组的二维数组,形状优先存储。 |
| n_dims | uint32_t | 表示每个形状数组的有效维度个数。 |
torq_tensor_attr
描述
TORQ 模型的 tensor 的属性。
成员
| 成员变量 | 数据类型 | 含义 |
|---|---|---|
| index | uint32_t | 表示输入输出 tensor 的索引位置。 |
| n_dims | uint32_t | tensor 维度个数。 |
| dims | uint32_t[] | tensor 形状。 |
| name | char[] | tensor 名称。 |
| n_elems | uint32_t | tensor 数据元素个数。 |
| size | uint32_t | tensor 数据所占内存大小。 |
| fmt | torq_tensor_format | tensor 维度的格式, 有以下格式:
|
| type | torq_tensor_type | tensor 数据类型, 有以下数据类型:
|
| qnt_type | torq_tensor_qnt_type | tensor 量化类型, 有以下的量化类型:
|
| fl | int8_t | 无效,占位预留。 |
| zp | int32_t | zero point,TORQ_TENSOR_QNT_AFFINE_ASYMMETRIC 量化类型的参数。 |
| scale | float | TORQ_TENSOR_QNT_AFFINE_ASYMMETRIC 量化类型的参数。 |
| w_stride | uint32_t | 无效,占位预留。 |
| size_with_stride | uint32_t | 无效,占位预留。 |
| pass_through | uint8_t |
|
| h_stride | uint32_t | 无效,占位预留。 |
torq_tensor_mem
描述
tensor 的内存信息。
成员
| 成员变量 | 数据类型 | 含义 |
|---|---|---|
| virt_addr | void* | tensor 的虚拟地址。 |
| phys_addr | uint64_t | tensor 的物理地址。 |
| fd | int32_t | tensor 的文件描述符。 |
| offset | int32_t | tensor 内存相较于文件描述符和虚拟地址的偏移量。 |
| size | uint32_t | tensor 占用的内存大 小。 |
| flags | uint32_t | torq_tensor_mem 的标志位。 |
| priv_data | void* | 内存的私有数据。 |
torq_input
描述
TORQ 模型的输入数据,作为参数传递给 torq_inputs_set 函数。
成员
| 成员变量 | 数据类型 | 含义 |
|---|---|---|
| index | uint32_t | 该输入的索引位置。 |
| buf | void* | 输入数据的指针。 |
| size | uint32_t | 输入数据所占内存大小。 |
| pass_through | uint8_t | pass_through=1 时,buf 存放的输入数据不做任何预处理(如归一化等),直接设为模型的输入节点。 |
| type | torq_tensor_type | 输入数据的类型。 |
| fmt | torq_tensor_format | 输入数据的格式。 |
torq_output
描述
TORQ 模型输出数据,作为参数传递给 torq_outputs_get 函数。在torq_outputs_get函数执行后,结构体将被赋值。
成员
| 成员变量 | 数据类型 | 含义 |
|---|---|---|
| want_float | uint8_t | 标识是否需要将输出数据转为 float 类型输出,该字段由用户设置。 |
| is_prealloc | uint8_t | 标识存放输出数据是否是预分配,该字段由用 户设置。 |
| index | uint32_t | 该输出的索引位置,该字段由用户设置。 |
| buf | void* | 输出数据的指针,该字段由接口返回。 |
| size | uint32_t | 输出数据所占内存大小,该字段由接口返回。 |
基础 API 说明
torq_init
描述
初始化函数,用于初始化 TORQ 上下文。
创建 torq_context对象(根据flag 和torq_init_extend结构体加载 TORQ 模型执行特定的初始化行为)。
参数
| 参数 | 数据类型 | 含义 |
|---|---|---|
| context | torq_context* | torq_context 指针。 |
| model | void* | 根据 size 的不同,可能为 TORQ 模型的二进制数据或者 TORQ 模型路径。
|
| size | uint32_t |
|
| flag | uint32_t | 预留初始化标志,默认初始化行为需要设置为 0。 |
| extend | torq_init_extend* | 预留初始化时的扩展信息。 |
返回值
int 错误码。详情见 TORQ 错误码。
示例代码
torq_context ctx;
int ret = torq_init(&ctx, model_data, model_data_size, 0, NULL);