CANN ops-nn ForeachExpm1 算子实战指南:aclnnForeachExpm1 两段式接口从原理到调用示例
CANN ops-nn ForeachExpm1 算子实战指南:aclnnForeachExpm1 两段式接口从原理到调用示例
本文是 CANN ops-nn 算子库中 ForeachExpm1(张量列表逐元素 e^x - 1 运算)算子的完整技术指南,围绕官方接口文档 aclnnForeachExpm1.md 展开,结合仓库中的算子定义、Kernel 实现、Tiling 与单算子 API 调用样例,系统讲解产品支持范围、接口参数约束、两段式调用流程、返回码语义与可编译运行的完整示例。读完本文,你将掌握如何在 Ascend NPU 上通过 aclnn 单算子 API 对一组张量批量执行 expm1 运算,并理解该算子在库内的实现机制。
一、算子功能与适用场景
ForeachExpm1 是一个典型的 foreach 系列批量一元算子:它接收一个**张量列表(TensorList)**作为输入,对列表中每个张量逐元素执行指数运算后再减 1,并将结果写入对应的输出张量列表。其数学定义如下:
与逐个调用单张量算子的方式相比,Foreach 系列接口把多个张量的同构运算合并为一次算子下发,显著减少 Host 侧调用开销,适合在 PyTorch 等框架的 foreach_ 优化器/梯度裁剪场景中批量处理参数张量列表。
产品支持情况
根据接口文档与 foreach_expm1/README.md 的说明,ForeachExpm1 在不同昇腾产品上的支持情况如下:
| 产品 | 是否支持 |
|---|---|
| Ascend 950PR / Ascend 950DT | 支持 |
| Atlas A3 训练系列产品 / Atlas A3 推理系列产品 | 支持 |
| Atlas A2 训练系列产品 / Atlas A2 推理系列产品 | 支持 |
| Atlas 200I/500 A2 推理产品 | 不支持 |
| Atlas 推理系列产品 | 不支持 |
| Atlas 训练系列产品 | 不支持 |
| Kirin X90 处理器系列产品 | 支持 |
| Kirin 9030 处理器系列产品 | 支持 |
注意:Kirin X90 / Kirin 9030 处理器系列不支持 BFLOAT16、INT16、INT8、UINT8 数据类型,仅支持 FLOAT16、FLOAT32。
从源码看,这一支持矩阵与 foreach_expm1_def.cpp 中通过 AICore().AddConfig(...) 注册的硬件配置一一对应:ascend910_93、ascend910b、ascend950 使用完整的数据类型列表(FLOAT16/FLOAT32/BFLOAT16/INT16/INT8/UINT8),而 Kirin 系列(kirinx90、kirin9030)通过 GetKirinCoreConfig() 仅注册了 FLOAT16 与 FLOAT32 两种类型。
二、两段式接口与函数原型
ForeachExpm1 遵循 CANN 单算子 API 的两段式接口规范(详见 两段式接口说明):必须先调用第一段接口 aclnnForeachExpm1GetWorkspaceSize 获取计算所需 workspace 大小以及封装了算子计算流程的执行器,再调用第二段接口 aclnnForeachExpm1 真正执行计算。
2.1 第一段接口
aclnnStatus aclnnForeachExpm1GetWorkspaceSize(
const aclTensorList *x,
const aclTensorList *out,
uint64_t *workspaceSize,
aclOpExecutor **executor)
该接口完成入参校验与 workspace 大小估算,输出 workspaceSize(Device 侧临时内存大小)和 executor(op 执行器,包含算子计算流程)。
2.2 第二段接口
aclnnStatus aclnnForeachExpm1(
void *workspace,
uint64_t workspaceSize,
aclOpExecutor *executor,
aclrtStream stream)
第二段接口负责在指定 stream 上异步下发计算任务。需要特别注意的是:第二段接口不能重复调用,同一 executor 不允许连续执行多次 aclnnForeachExpm1(...),否则会出现异常。
三、第一段接口参数详解
3.1 参数说明
| 参数名 | 输入/输出 | 描述 | 使用说明 | 数据类型 | 数据格式 | 维度(shape) | 非连续Tensor |
|---|---|---|---|---|---|---|---|
| x(aclTensorList*) | 输入 | 表示进行指数运算然后减 1 运算的输入张量列表,对应公式中的 x |
支持空 Tensor;该参数中所有 Tensor 的数据类型保持一致;数据类型和数据格式与出参 out 的数据类型和数据格式一致 |
BFLOAT16、FLOAT16、FLOAT32、INT16、INT8、UINT8 | ND | 0-8 | √ |
| out(aclTensorList*) | 输出 | 表示进行指数运算然后减 1 运算的输出张量列表,对应公式中的 y |
支持空 Tensor;该参数中所有 Tensor 的数据类型保持一致;当 x 的数据类型为 INT16、INT8、UINT8 时,数据类型为 FLOAT32,其他情况下与入参 x 的数据类型一致;数据格式与入参 x 的数据格式一致,shape size 大于等于入参 x 的 shape size |
BFLOAT16、FLOAT16、FLOAT32 | ND | 0-8 | √ |
| workspaceSize(uint64_t*) | 输出 | 返回需要在 Device 侧申请的 workspace 大小 | - | - | - | - | - |
| executor(aclOpExecutor**) | 输出 | 返回 op 执行器,包含了算子计算流程 | - | - | - | - | - |
几点关键约束值得注意:
- 整数输入自动提升:当输入
x是 INT16/INT8/UINT8 整数类型时,输出out必须为 FLOAT32;浮点输入(BFLOAT16/FLOAT16/FLOAT32)则输出与输入同类型。这一点在算子定义 foreach_expm1_def.cpp 中有直接体现——output_dtype_list为{FLOAT16, FLOAT, BF16, FLOAT, FLOAT, FLOAT},与输入类型列表逐索引配对,整数类型的输出统一为 FLOAT。 - 支持非连续 Tensor:参数表中"非连续 Tensor"列为 √,表示输入输出允许存在非连续内存布局。
- shape 兼容规则:输出 shape size 需大于等于输入 shape size,各张量维度不超过 8 维(0-8)。
3.2 返回值与错误码
第一段接口返回 aclnnStatus 状态码(完整返回码含义参见 aclnn 返回码说明),在入参校验不通过时报错场景如下:
| 返回码 | 错误码 | 描述 |
|---|---|---|
| ACLNN_ERR_PARAM_NULLPTR | 161001 | 传入的 x 或 out 是空指针 |
| ACLNN_ERR_PARAM_INVALID | 161002 | x 或 out 的数据类型不在支持的范围之内 |
| ACLNN_ERR_PARAM_INVALID | 161002 | x 和 out 的数据类型不一致 |
| ACLNN_ERR_INNER_TILING_ERROR | 561002 | x 与 out 的 shape 不满足约束 |
| ACLNN_ERR_INNER_TILING_ERROR | 561002 | x 或 out 中的 Tensor 的数据类型不一致 |
| ACLNN_ERR_INNER_TILING_ERROR | 561002 | x 或 out 中的 Tensor 维度超过 8 维 |
四、第二段接口参数详解
| 参数名 | 输入/输出 | 描述 |
|---|---|---|
| workspace | 输入 | 在 Device 侧申请的 workspace 内存地址 |
| workspaceSize | 输入 | 在 Device 侧申请的 workspace 大小,由第一段接口 aclnnForeachExpm1GetWorkspaceSize 获取 |
| executor | 输入 | op 执行器,包含了算子计算流程 |
| stream | 输入 | 指定执行任务的 Stream |
第二段接口同样返回 aclnnStatus 状态码。
五、约束说明
- 确定性计算:
aclnnForeachExpm1为默认确定性实现,即相同输入、相同环境条件下多次执行结果一致,适合对可复现性有要求的训练与调试场景。
六、完整调用示例(可编译运行)
以下示例代码演示如何在 Host 侧通过两段式接口调用 ForeachExpm1 算子,对两个不同 shape 的张量执行 e^x - 1 运算。完整代码同样收录于仓库 examples/test_aclnn_foreach_expm1.cpp,具体编译与执行过程请参考 编译与运行样例。
#include <iostream>
#include <vector>
#include "acl/acl.h"
#include "aclnnop/aclnn_foreach_expm1.h"
#define CHECK_RET(cond, return_expr) \
do { \
if (!(cond)) { \
return_expr; \
} \
} while (0)
#define LOG_PRINT(message, ...) \
do { \
printf(message, ##__VA_ARGS__); \
} while (0)
int64_t GetShapeSize(const std::vector<int64_t>& shape) {
int64_t shapeSize = 1;
for (auto i : shape) {
shapeSize *= i;
}
return shapeSize;
}
int Init(int32_t deviceId, aclrtStream *stream)
{
// 固定写法,资源初始化
auto ret = aclInit(nullptr);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclInit failed. ERROR: %d\n", ret); return ret);
ret = aclrtSetDevice(deviceId);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtSetDevice failed. ERROR: %d\n", ret); return ret);
ret = aclrtCreateStream(stream);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtCreateStream failed. ERROR: %d\n", ret); return ret);
return 0;
}
template <typename T>
int CreateAclTensor(const std::vector<T>& hostData, const std::vector<int64_t>& shape, void** deviceAddr,
aclDataType dataType, aclTensor** tensor) {
auto size = GetShapeSize(shape) * sizeof(T);
// 调用aclrtMalloc申请device侧内存
auto ret = aclrtMalloc(deviceAddr, size, ACL_MEM_MALLOC_HUGE_FIRST);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtMalloc failed. ERROR: %d\n", ret); return ret);
// 调用aclrtMemcpy将host侧数据复制到device侧内存上
ret = aclrtMemcpy(*deviceAddr, size, hostData.data(), size, ACL_MEMCPY_HOST_TO_DEVICE);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtMemcpy failed. ERROR: %d\n", ret); return ret);
// 计算连续tensor的strides
std::vector<int64_t> strides(shape.size(), 1);
for (int64_t i = shape.size() - 2; i >= 0; i--) {
strides[i] = shape[i + 1] * strides[i + 1];
}
// 调用aclCreateTensor接口创建aclTensor
*tensor = aclCreateTensor(shape.data(), shape.size(), dataType, strides.data(), 0, aclFormat::ACL_FORMAT_ND,
shape.data(), shape.size(), *deviceAddr);
return 0;
}
int main() {
// 1. (固定写法)device/stream初始化,参考acl API手册
// 根据自己的实际device填写deviceId
int32_t deviceId = 0;
aclrtStream stream;
auto ret = Init(deviceId, &stream);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("Init acl failed. ERROR: %d\n", ret); return ret);
// 2. 构造输入与输出,需要根据API的接口自定义构造
std::vector<int64_t> selfShape1 = {2, 3};
std::vector<int64_t> selfShape2 = {1, 3};
std::vector<int64_t> outShape1 = {2, 3};
std::vector<int64_t> outShape2 = {1, 3};
void* input1DeviceAddr = nullptr;
void* input2DeviceAddr = nullptr;
void* out1DeviceAddr = nullptr;
void* out2DeviceAddr = nullptr;
aclTensor* input1 = nullptr;
aclTensor* input2 = nullptr;
aclTensor* out1 = nullptr;
aclTensor* out2 = nullptr;
std::vector<float> input1HostData = {1, 2, 3, 4, 5, 6};
std::vector<float> input2HostData = {7, 8, 9};
std::vector<float> out1HostData(6, 0);
std::vector<float> out2HostData(3, 0);
// 创建input1 aclTensor
ret = CreateAclTensor(input1HostData, selfShape1, &input1DeviceAddr, aclDataType::ACL_FLOAT, &input1);
CHECK_RET(ret == ACL_SUCCESS, return ret);
// 创建input2 aclTensor
ret = CreateAclTensor(input2HostData, selfShape2, &input2DeviceAddr, aclDataType::ACL_FLOAT, &input2);
CHECK_RET(ret == ACL_SUCCESS, return ret);
// 创建out1 aclTensor
ret = CreateAclTensor(out1HostData, outShape1, &out1DeviceAddr, aclDataType::ACL_FLOAT, &out1);
CHECK_RET(ret == ACL_SUCCESS, return ret);
// 创建out2 aclTensor
ret = CreateAclTensor(out2HostData, outShape2, &out2DeviceAddr, aclDataType::ACL_FLOAT, &out2);
CHECK_RET(ret == ACL_SUCCESS, return ret);
std::vector<aclTensor*> tempInput{input1, input2};
aclTensorList* tensorListInput = aclCreateTensorList(tempInput.data(), tempInput.size());
std::vector<aclTensor*> tempOutput{out1, out2};
aclTensorList* tensorListOutput = aclCreateTensorList(tempOutput.data(), tempOutput.size());
// 3. 调用CANN算子库API,需要修改为具体的API名称
uint64_t workspaceSize = 0;
aclOpExecutor* executor;
// 调用aclnnForeachExpm1第一段接口
ret = aclnnForeachExpm1GetWorkspaceSize(tensorListInput, tensorListOutput, &workspaceSize, &executor);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnForeachExpm1GetWorkspaceSize failed. ERROR: %d\n", ret); return ret);
// 根据第一段接口计算出的workspaceSize申请device内存
void* workspaceAddr = nullptr;
if (workspaceSize > 0) {
ret = aclrtMalloc(&workspaceAddr, workspaceSize, ACL_MEM_MALLOC_HUGE_FIRST);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("allocate workspace failed. ERROR: %d\n", ret); return ret);
}
// 调用aclnnForeachExpm1第二段接口
ret = aclnnForeachExpm1(workspaceAddr, workspaceSize, executor, stream);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnForeachExpm1 failed. ERROR: %d\n", ret); return ret);
// 4. (固定写法)同步等待任务执行结束
ret = aclrtSynchronizeStream(stream);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtSynchronizeStream failed. ERROR: %d\n", ret); return ret);
// 5. 获取输出的值,将device侧内存上的结果复制至host侧,需要根据具体API的接口定义修改
auto size = GetShapeSize(outShape1);
std::vector<float> out1Data(size, 0);
ret = aclrtMemcpy(out1Data.data(), out1Data.size() * sizeof(out1Data[0]), out1DeviceAddr,
size * sizeof(out1Data[0]), ACL_MEMCPY_DEVICE_TO_HOST);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("copy result from device to host failed. ERROR: %d\n", ret); return ret);
for (int64_t i = 0; i < size; i++) {
LOG_PRINT("out1 result[%ld] is: %f\n", i, out1Data[i]);
}
size = GetShapeSize(outShape2);
std::vector<float> out2Data(size, 0);
ret = aclrtMemcpy(out2Data.data(), out2Data.size() * sizeof(out2Data[0]), out2DeviceAddr,
size * sizeof(out2Data[0]), ACL_MEMCPY_DEVICE_TO_HOST);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("copy result from device to host failed. ERROR: %d\n", ret); return ret);
for (int64_t i = 0; i < size; i++) {
LOG_PRINT("out2 result[%ld] is: %f\n", i, out2Data[i]);
}
// 6. 释放aclTensor,需要根据具体API的接口定义修改
aclDestroyTensorList(tensorListInput);
aclDestroyTensorList(tensorListOutput);
// 7.释放device资源,需要根据具体API的接口定义修改
aclrtFree(input1DeviceAddr);
aclrtFree(input2DeviceAddr);
aclrtFree(out1DeviceAddr);
aclrtFree(out2DeviceAddr);
if (workspaceSize > 0) {
aclrtFree(workspaceAddr);
}
aclrtDestroyStream(stream);
aclrtResetDevice(deviceId);
aclFinalize();
return 0;
}
该示例的执行流程可归纳为六步:
- 初始化:
aclInit→aclrtSetDevice→aclrtCreateStream; - 构造张量:通过
aclrtMalloc/aclrtMemcpy准备 Device 侧数据,用aclCreateTensor创建aclTensor,再用aclCreateTensorList组装输入/输出张量列表(示例中两个输入张量 shape 分别为{2,3}和{1,3},输出 shape 与之对应); - 两段式调用:先调
aclnnForeachExpm1GetWorkspaceSize拿到workspaceSize与executor,按需aclrtMalloc申请 workspace,再调aclnnForeachExpm1下发计算; - 同步等待:
aclrtSynchronizeStream确保任务完成; - 取回结果:
aclrtMemcpy将输出从 Device 复制到 Host 并打印(例如输入{1,2,3,4,5,6}对应输出约为{1.718, 6.389, 19.085, 53.598, 147.413, 402.429}); - 释放资源:销毁 TensorList、释放 Device 内存与 workspace、销毁 stream 并
aclFinalize。
七、源码级实现剖析
为了让读者更深入理解该算子的底层行为,本节结合仓库源码补充几个关键实现事实。
7.1 算子定义:数据类型配对与平台注册
foreach_expm1_def.cpp 通过 OpDef 声明了算子的输入输出原型:
- 输入
x支持FLOAT16/FLOAT32/BFLOAT16/INT16/INT8/UINT8六种类型,格式均为ND,ParamType(DYNAMIC)表示动态输入; - 输出
y的类型列表与输入按索引配对,整数输入对应 FLOAT 输出(源码注释明确说明"整数输入按索引配对提升 float32 输出,浮点输入输出同 dtype"); - 通过
AICore().AddConfig(...)分别注册ascend910_93、ascend910b、ascend950及 Kirin 系列平台,其中 ascend950 配置开启了DynamicRankSupportFlag、DynamicShapeSupportFlag、PrecisionReduceFlag等动态能力。
7.2 Kernel 实现:向量流水与 SIMT 两种路径
不同架构的 Kernel 入口采用了不同的实现路径:
- 通用路径 op_kernel/foreach_expm1.cpp 按
TILING_KEY分发:FLOAT16/FLOAT32 走ForeachImplictOutput模板,BFLOAT16/INT16/INT8/UINT8 走ForeachIntToFloatUnary模板(来自 foreach_utils 公共实现),核心计算由Expm1Adapter完成——先在向量流水上执行Exp得到e^x,再执行Adds加-1,两次向量指令间以PipeBarrier<PIPE_V>()保证流水同步; - arch35(Ascend 950)路径 op_kernel/arch35/foreach_expm1.cpp 采用 **SIMT 向量函数(VF)**实现,见 foreach_expm1_simt.h:固定 1024 线程,先按
tensorId从 TensorList 中解析每个张量的 GM 地址(SimtGetTensorAddr),再按线程网格步长遍历元素,对每个元素调用expm1f计算,整数输入在 SIMT 路径同样先转 float 计算再回写。
7.3 Tiling 与二进制配置
Host 侧 Tiling 在 foreach_expm1_tiling_arch35.cpp 中实现:从平台信息读取 AIV 核数与 UB 内存大小,遍历 TensorList 中每个张量,将其元素个数写入 ForeachExpm1TilingData(结构体见 foreach_expm1_tiling_data.h,包含 tensorCount、totalElements 与最多 256 个张量的 tensorElements 数组),供 Kernel 端按张量逐个调度。
此外,各平台目录下维护了算子二进制配置文件,例如 ascend910b/foreach_expm1_binary.json 按 dtype 组合(float16→float16、float32→float32、bfloat16→bfloat16、int16→float32、int8→float32、uint8→float32)各注册一条二进制记录,shape 为 [-2] 表示动态 shape,与文档参数表完全一致。
7.4 测试与验证
仓库为该算子提供了完整的 UT/ST 测试链:
- Host 侧单测:
foreach/foreach_expm1/tests/ut/op_host/下的 infershape 与 arch22/arch35 两套 tiling 测试,覆盖 shape 推导与多平台 Tiling 逻辑; - Kernel 侧单测:
foreach/foreach_expm1/tests/ut/op_kernel/test_foreach_expm1.cpp配合expm1_data/gen_data.py、compare_data.py生成/比对测试数据; - 系统测试:
foreach/foreach_expm1/tests/st/aclnnForeachExpm1/下的 ATK 用例(atk_aclnnForeachExpm1.json与executor_aclnnForeachExpm1.py)用于端到端验证 aclnn 接口行为。
八、常见问题与注意事项
- 第二段接口重复调用:同一
executor不支持连续多次执行aclnnForeachExpm1,每次执行应重新走一遍两段式流程; - workspace 内存:只有当
workspaceSize > 0时才需要aclrtMalloc申请,示例代码对此做了判空处理;从 Kernel 源码看,foreach 向量路径userWS = nullptr,即大部分场景无需额外 workspace; - 整数输入精度:INT16/INT8/UINT8 输入会先提升为 FLOAT32 计算,输出 dtype 为 FLOAT32,若业务要求半精度输出请自行 cast;
- shape 匹配:输出 shape size 需不小于输入,各张量维度不得超过 8 维,且 TensorList 内所有张量 dtype 必须一致;
- 平台差异:Atlas 200I/500 A2 推理产品、Atlas 推理系列产品与 Atlas 训练系列产品不支持本算子,调用前请确认目标硬件型号。
九、参考链接
- 官方接口文档:aclnnForeachExpm1.md
- 算子 README 与调用方式总览:foreach_expm1/README.md
- 可编译运行样例:examples/test_aclnn_foreach_expm1.cpp
- 算子定义(dtype/format/平台注册):foreach_expm1_def.cpp
- Kernel 入口与公共模板实现:foreach_expm1.cpp、foreach_int_to_float_unary.h
- 架构概念:两段式接口、aclnn 返回码、编译与运行样例